 |
HP C
HP C
Language Reference Manual
9.15 String Processing (<string.h>)
The <string.h> header file declares one type and several
functions, and defines one macro useful for manipulating character
arrays that other objects treat as character arrays.
There are two kinds of string functions declared. The first, with names
beginning with str, manipulate character arrays; the second,
with names beginning with mem, manipulate other objects
treated as character arrays. Except for memmove, function
behavior is undefined if copying takes place between overlapping
objects.
Type
size_t
- An unsigned integral type of the result of the sizeof
operator.
Macro
NULL
- Expands to an implementation-defined null pointer constant.
Functions
void *memcpy(void *s1, const void *s2, size_t
n);
- Copies n characters from the object pointed to by
s2 to the object pointed to by s1. The function
returns s1.
void *memmove(void *s1, const void *s2, size_t
n);
- Copies n characters from the object pointed to by
s2 to the object pointed to by s1. Copying takes
place as if the n characters from the object pointed to by
s2 are first copied into a temporary array of n
characters that does not overlap the object pointed to by s1
and s2, and then the n characters from the temporary
array are copied into the object pointed to by s1. The
memmove function returns s1.
void *memchr(const void *s, int c, size_t
n);
- Locates the first occurrence of c (converted to an
unsigned char) in the first n unsigned characters of
the object pointed to by s. The memchr function
returns a pointer to the located character, or a null pointer if the
character was not found.
int memcmp(const void *s1, const void *s2, size_t
n);
- Compares the first n characters of the object pointed to
by s1 to the first n characters of the object pointed
to by s2. The memcmp function returns an integer less
than, equal to, or greater than 0, depending on whether the object
pointed to by s1 is less than, equal to, or greater than the
object pointed to by s2.
void *memset(void *s, int c, size_t n);
- Copies the value of c (converted to an unsigned char) into
each of the first n characters pointed to by s. The
function returns s.
char *strcpy(char *s1, const char *s2);
- Copies the string pointed to by s2 (including the
terminating null character) to the string pointed to by s1.
The strcpy function returns s1.
char *strncpy(char *s1, const char *s2, size_t
n);
- Copies no more than n characters from the string pointed
to by s2 to the string pointed to by s1, up to but
not including the null terminator of the string pointed to by
s2; returns s1. If the string pointed to by
s2 is less than n characters, strncpy pads
the copy with null characters.
char *strcat(char *s1, const char *s2);
- Appends a copy of the the string pointed to by s2
(including the terminating null character) to the end of the string
pointed to by s1. The strcat function returns
s1. The first character of s2 overwrites the null
character of s1.
char *strncat(char *s1, const char *s2, size_t
n);
- Appends no more than n characters from the string pointed
to by s2 (up to but not including a null character) to the
string pointed to by s1. The strncat function returns
s1. The first character of s2 overwrites the null
character of s1. A terminating null character is appended to
the result. The first character of s2 overwrites the null
character of s1.
int strcmp(const char *s1, const char *s2);
- Compares the string pointed to by s1 to the string pointed
to by s2. The strcmp function returns an integer less
than, equal to, or greater than 0, depending on whether the string
pointed to by s1 is less than, equal to, or greater than the
string pointed to by s2.
int strcoll(const char *s1, const char *s2);
- Compares the string pointed to by s1 to the string pointed
to by s2, both interpreted as appropriate to the
LC_COLLATE category of the current locale (see Section 9.6).
The strcoll function returns an integer less than, equal to,
or greater than 0, depending on whether the string pointed to by
s1 is less than, equal to, or greater than the string pointed
to by s2, when both are interpreted as appropriate to the
current locale.
int strncmp(const char *s1, const char *s2,
size_t n);
- Compares no more than n characters from the string pointed
to by s1 to the string pointed to by s2. The strings
are compared until a null character is encountered, the strings differ,
or n is reached. The strncmp function returns an
integer less than, equal to, or greater than 0, depending on whether
the string pointed to by s1 is less than, equal to, or greater
than the string pointed to by s2.
size_t strxfrm(char *s1, const char *s2, size_t
n);
- Transforms the string pointed to by s2 and places the
resulting string into the array pointed to by s1.
See your
HP C library routine documentation for a detailed description
of this function.
char *strchr(const char *s, int c);
- Locates the first occurrence of c (converted to a
char) in the string pointed to by s. The terminating
null character is considered to be part of the string. The function
returns a pointer to the located character, or a null pointer if the
character was not found.
size_t strcspn(const char *s1, const char
*s2);
- Computes the length of the maximum initial segment of the string
pointed to by s1 that consists entirely of characters not
found in the string pointed to by s2. The strcspn
function returns the length of the segment.
char *strpbrk(const char *s1, const char
*s2);
- Locates the first occurrence in the string pointed to by
s1 of any character from the string pointed to by s2.
The function returns a pointer to the character, or a null pointer if
no character in s1 occurs in s2.
char *strrchr(const char *s, int c);
- Locates the last occurrence of c (converted to a
char) in the string pointed to by s. The terminating
null character is considered to be part of the string. The function
returns a pointer to the located character, or a null pointer if the
character was not found.
size_t strspn(const char *s1, const char
*s2);
- Computes the length of the maximum initial segment of the string
pointed to by s1 that consists entirely of characters from the
string pointed to by s2. The strspn function returns
the length of the segment.
char *strstr(const char *s1, const char *s2);
- Locates the first occurrence in the string pointed to by
s1 of the sequence of characters (excluding the terminal null
character) in the string pointed to by s2. The strstr
function returns a pointer to the located string, or a null pointer if
the string was not found. If s2 points to a string of zero
length, the function returns s1.
char *strtok(const char *s1, char *s2);
- Breaks the string pointed to by s1 into a sequence of
tokens, each of which is delimited by a character from the string
pointed to by s2. The first call to strtok() skips
characters, looking for the first one that is not in s2. The
function keeps track of its position in the string pointed to by
s1 between calls and, as successive calls are made, the
function works through this string, identifying the text token
following the one identified by the previous call. When the function
finds a character in s1 that matches a character in
s2, it replaces the character in s1 with a null
character. The strtok function returns a pointer to the first
character of the token, or a null pointer if there is no token.
char *strerror(int errnum);
- Maps the error number in errnum to an error message
string; returns a pointer to the string. The string pointed to must not
be modified by the program, but can be overwritten by a subsequent call
to strerror.
size_t strlen(const char *s);
- Computes the length of the string pointed to by s. The
function returns the number of characters that precede the terminating
null character.
9.16 Type-generic Math (<tgmath.h>)
The header <tgmath.h> includes the headers
<math.h> and <complex.h> and defines
several type-generic macros.
Of the <math.h> and <complex.h> functions
without an f (float) or l (long double) suffix,
several have one or more parameters whose corresponding real type is
double. For each such function, except modf, there is
a corresponding type-generic macro.1 The parameters whose
corresponding real type is double in the function synopsis are
generic parameters. Use of the macro invokes a function whose
corresponding real type and type domain are determined by the arguments
for the generic parameters.2
Note
The type-generic implementation of the absolute value function
(fabs) is not available for complex types in this release. You
must use the type-specific names (cabs, cabsf,
cabsl) instead.
|
9.16.1 Real-Type Determination
Use of the macro invokes a function whose generic parameters have the
corresponding real type determined as follows:
- First, if any argument for generic parameters has type long
double, the type determined is long double.
- Otherwise, if any argument for generic parameters has type
double or is of integer type, the type determined is
double.
- Otherwise, the type determined is float.
9.16.2 Unsuffixed Functions in (<math.h>) and (<complex.h>) with the Same Name
For each unsuffixed function in <math.h> for which there
is a function in <complex.h> with the same name except
for a c prefix, the corresponding type-generic macro (for both
functions) has the same name as the function in
<math.h>. The corresponding type-generic macro for
fabs and cabs is fabs. These functions are:
<math.h> <complex.h> type-generic
function function macro
----------- ------------- -------------
acos cacos acos
asin casin asin
atan catan atan
acosh cacosh acosh
asinh casinh asinh
atanh catanh atanh
cos ccos cos
sin csin sin
tan ctan tan
cosh ccosh cosh
sinh csinh sinh
tanh ctanh tanh
exp cexp exp
log clog log
pow cpow pow
sqrt csqrt sqrt
fabs cabs fabs
|
If at least one argument for a generic parameter is complex, then use
of the macro invokes a complex function; otherwise, use of the macro
invokes a real function.
9.16.3 Unsuffixed Functions in (<math.h>) with no c-prefixed Counterpart in (<complex.h>)
For each unsuffixed function in <math.h> without a
c-prefixed counterpart in <complex.h>, the corresponding
type-generic macro has the same name as the function. These
type-generic macros are:
atan2 fma llround remainder
cbrt fmax log10 remquo
ceil fmin log1p rint
copysign fmod log2 round
erf frexp logb scalbn
erfc hypot lrint scalbln
exp2 ilogb lround tgamma
expm1 ldexp nearbyint trunc
fdim lgamma nextafter
floor llrint nexttoward
|
If all arguments for generic parameters are real, then use of the macro
invokes a real function; otherwise, use of the macro results in
undefined behavior.
9.16.4 Unsuffixed Functions in (<complex.h>) that are not c-prefixed Counterparts to Functions in (<math.h>)
For each unsuffixed function in <complex.h> that is not
a c-prefixed counterpart to a function in <math.h>, the
corresponding type-generic macro has the same name as the function:
carg conj creal
cimag cproj
|
Use of the macro with any real or complex argument invokes a complex
function.
9.16.5 Example
Consider the following declarations:
#include <tgmath.h>
int n;
float f;
double d;
long double ld;
float complex fc;
double complex dc;
long double complex ldc;
|
Given these declarations, functions invoked by use of type-generic
macros are as follows:
macro use invokes
---------------- -----------------------------
exp(n) exp(n), the function
acosh(f) acoshf(f)
sin(d) sin(d), the function
atan(ld) atanl(ld)
log(fc) clogf(fc)
sqrt(dc) csqrt(dc)
pow(ldc, f) cpowl(ldc, f)
remainder(n, n) remainder(n, n), the function
nextafter(d, f) nextafter(d, f), the function
nexttoward(f, ld) nexttowardf(f, ld)
copysign(n, ld) copysignl(n, ld)
ceil(fc) undefined behavior
rint(dc) undefined behavior
fmax(ldc, ld) undefined behavior
carg(n) carg(n), the function
cproj(f) cprojf(f)
creal(d) creal(d), the function
cimag(ld) cimagl(ld)
cabs(fc) cabsf(fc)
carg(dc) carg(dc), the function
cproj(ldc) cprojl(ldc)
|
9.16.6 Imaginary Arguments
Type-generic macros that accept complex arguments also accept imaginary
arguments. If an argument is imaginary, the macro expands to an
expression whose type is real, imaginary, or complex, as appropriate
for the particular function: if the argument is imaginary, then the
types of cos, cosh, fabs, carg,
cimag, and creal are real; the types of sin,
tan, sinh, tanh, asin,
atan, asinh, and atanh are imaginary; and
the types of the others are complex.
Given an imaginary argument, each of the type-generic macros
cos, sin, tan, cosh, sinh,
tanh, asin, atan, asinh,
atanh is specified by a formula in terms of real functions:
cos(iy) = cosh(y)
sin(iy) = i sinh(y)
tan(iy) = i tanh(y)
cosh(iy) = cos(y)
sinh(iy) = i sin(y)
tanh(iy) = i tan(y)
asin(iy) = i asinh(y)
atan(iy) = i atanh(y)
asinh(iy) = i asin(y)
atanh(iy) = i atan(y)
|
Note
1 Like other function-like macros in
Standard libraries, each type-generic macro can be suppressed to make
available the corresponding ordinary function.
2 If the type of the argument is not
compatible with the type of the parameter for the selected function,
the behavior is undefined.
|
9.17 Date and Time (<time.h>)
The <time.h> header file defines two macros, and
declares four types and several functions for manipulating time and
date information. Some functions process local time, which may differ
from calendar time because of time zone.
Types
size_t
- An unsigned integral type of the result of the sizeof
operator.
- Arithmetic types capable of representing times.
struct tm
- Holds the components of a calendar time, called the broken-down
time. The structure contains the following members:
int tm_sec; /* seconds after the minute -- [0,61] */
int tm_min; /* minutes after the hour -- [0,59] */
int tm_hour; /* hours since midnight -- [0,23] */
int tm_mday; /* day of the month -- [1,31] */
int tm_mon; /* months since January -- [0,11] */
int tm_year; /* years since 1900 */
int tm_wday; /* days since Sunday -- [0,6] */
int tm_yday; /* days since January 1 -- [0,365] */
int tm_isdst; /* Daylight Saving Time flag -- 0 if */
/* DST not in effect; positive if it is; */
/* negative if information is not available. */
|
Macros
NULL
- Expands to an implementation-defined null pointer constant.
CLOCKS_PER_SEC
- The number per second of the value returned by the clock
function.
Time Conversion Functions
char *asctime(const struct tm *timeptr);
- Converts a broken-down time in the structure pointed to by
timeptr into a 26-character string in the form of this example:
Sat Sep 08 08:10:32 1990\n\0
|
A pointer to the string is returned.
char *ctime(const time_t *timer);
- Converts the calendar time pointed to by timer to local
time in a string of the form generated by the asctime
function. A pointer to the string is returned. The ctime
function is equivalent to the following:
asctime(localtime(timer))
|
struct tm *gmtime(const time_t *timer);
- Converts the calendar time pointed to by timer into a
broken-down time expressed as Coordinated Universal Time (UTC). The
gmtime function returns a pointer to the broken-down time, or
a null pointer if UTC is not available.
struct tm *localtime(const time_t *timer);
- Converts the calendar time pointed to by timer into a
broken-down time expressed as local time. The localtime
function returns a pointer to the broken-down time.
size_t strftime(char *s, size_t maxsize, const char
*format, const struct tm *timeptr);
- Places characters into the array pointed to by s as
controlled by the string pointed to by format. The format
string consists of zero or more conversion specifiers and ordinary
multibyte characters. All ordinary multibyte characters (including the
terminating null character) are copied unchanged into the array. Each
conversion specifier is replaced by the appropriate characters as shown
in Table 9-2. The appropriate characters are determined by the
LC_TIME category of the current locale and by the values
contained in the structure pointed to by timeptr.
Table 9-2 strftime Conversion Specifiers
| Specifier |
Replaced by |
|
%a
|
The locale's abbreviated weekday name
|
|
%A
|
The locale's full weekday name
|
|
%b
|
The locale's abbreviated month name
|
|
%B
|
The locale's full month name
|
|
%c
|
The locale's appropriate date and time representation
|
|
%d
|
The day of the month as a decimal number (01 -- 31)
|
|
%H
|
The hour (24-hour clock) as a decimal number (00 -- 23)
|
|
%I
|
The hour (12-hour clock) as a decimal number (01 -- 12)
|
|
%j
|
The day of the year as a decimal number (001 -- 366)
|
|
%m
|
The month as a decimal number (01 -- 12)
|
|
%M
|
The minute as a decimal number (00 -- 59)
|
|
%p
|
The locale's equivalent of the AM/PM designations associated with a
12-hour clock
|
|
%S
|
The second as a decimal number (00 -- 61)
|
|
%U
|
The week number of the year (the first Sunday as the first day of week
1) as a decimal number (00 -- 53)
|
|
%w
|
The weekday as a decimal number (0 [Sunday] -- 6)
|
|
%W
|
The week number of the year (the first Monday as the first day of week
1) as a decimal number (00 -- 53)
|
|
%x
|
The locale's appropriate date representation
|
|
%X
|
The locale's appropriate time representation
|
|
%y
|
The year without century as a decimal number (00 -- 99)
|
|
%Y
|
The year with century as a decimal number
|
|
%Z
|
The time zone name or abbreviation, or by no characters if no time zone
can be determined
|
|
%%
|
%
|
If the total number of resulting characters including the
terminating null character is not more than maxsize, the
strftime function returns the number of characters placed into
the array pointed to by s, not including the terminating null
character. Otherwise, 0 is returned, and the array contents are
indeterminate.
Time Manipulation Functions
clock_t clock(void);
- Determines the processor time used. The clock function
returns the processor time used by the program since the beginning of
an event related to the program invocation. To determine the time in
seconds, divide the return value by the value of the
CLOCKS_PER_SEC macro. If the processor time is not available
or cannot be represented, the value returned is (clock_t)-1.
(To measure the time spent in a program, call the clock
function at the start of the program and subtract the return value from
that of subsequent calls.)
|
