| United States |
|
|
|
| Previous | Contents | Index |
Copies wide characters from wstr_2 into wstr_1. The function copies up to a maximum of maxchar characters.
#include <wchar.h>Function Variants This function also has variants named _wcsncpy32 and _wcsncpy64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 for more information on using pointer-size-specific functions.wchar_t *wcsncpy (wchar_t *wstr_1, const wchar_t *wstr_2, size_t maxchar);
wstr_1, wstr_2
Pointers to null-terminated wide-character strings.maxchar
The maximum number of wide characters to copy from wstr_2 to wstr_1.
This function copies no more than maxchar characters from wstr_2 to wstr_1. If wstr_2 contains less than maxchar characters, null characters are added to wstr_1 until maxchar characters have been written to wstr_1.If wstr_2 contains maxchar or more characters, as many characters as possible are copied to wstr_1. The null terminator of wstr_2 is not copied to wstr_1.
See also wcscpy in this section.
x The address of wstr_1.
Searches a wide-character string for the first occurrence of one of a specified set of wide characters.
#include <wchar.h>Function Variants This function also has variants named _wcspbrk32 and _wcspbrk64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 for more information on using pointer-size-specific functions.wchar_t *wcspbrk (const wchar_t *wstr, const wchar_t *charset);
wstr
A pointer to a wide-character string. If this is a null string, NULL is returned.charset
A pointer to a wide-character string containing the set of wide characters for which the function will search.
This function scans the wide characters in the string, stops when it encounters a wide character found in charset, and returns the address of the first character in the string that appears in the character set.
x The address of the first wide character in the string that is in the set. NULL Indicates that none of the characters are in charset.
Scans for the last occurrence of a wide-character in a given string.
#include <wchar.h>Function Variants This function also has variants named _wcsrchr32 and _wcsrchr64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 for more information on using pointer-size-specific functions.wchar_t *wcsrchr (const wchar_t *wstr, wchar_t wc);
wstr
A pointer to a null-terminated wide-character string.wc
A character of type wchar_t .
This function returns the address of the last occurrence of a given wide character in a null-terminated wide-character string. The terminating null character is considered to be part of the string.See also wcschr in this section.
x The address of the last occurrence of the specified wide character. NULL Indicates that the wide character does not occur in the string.
#include <stdlib.h> #include <stdio.h> #include <wchar.h> #include <string.h> #define BUFF_SIZE 50 #define STRING_SIZE 6 main() { int i; wchar_t s1buf[BUFF_SIZE], w_string[STRING_SIZE]; wchar_t *status; wchar_t *pbuf = s1buf; /* Initialize the buffer */ if (mbstowcs(s1buf, "hijklabcdefg ytuhijklfedcba", BUFF_SIZE) == -1) { perror("mbstowcs"); exit(EXIT_FAILURE); } /* Initialize the string to be searched for */ if (mbstowcs(w_string, "hijkl", STRING_SIZE) == -1) { perror("mbstowcs"); exit(EXIT_FAILURE); } /* This program checks the wcsrchr function by searching for the */ /* last occurrence of a string in the buffer s1buf and prints out */ /* the contents of s1buff from the location of the string found. */ status = wcsrchr(s1buf, w_string[0]); /* Check for pointer to start of rightmost character string. */ if (status == pbuf) { printf("Error in wcsrchr\n"); exit(EXIT_FAILURE); } printf("Program completed successfully\n"); printf("String found : [%S]\n", status); }Running the example produces the following result:
Program completed successfully String found : [hijklfedcba]
Converts a sequence of wide characters into a sequence of corresponding multibyte characters.
#include <wchar.h>Function Variants This function also has variants named _wcsrtombs32 and _wcsrtombs64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 for more information on using pointer-size-specific functions.size_t wcsrtombs (char *dst, const wchar_t **src, size_t len, mbstate_t *ps);
dst
A pointer to the destination array for converted multibyte character sequence.src
An address of the pointer to an array containing the sequence of wide characters to be converted.len
The maximum number of bytes that can be stored in the array pointed to by dst.ps
A pointer to the mbstate_t object. If a NULL pointer is specified, the function uses its internal mbstate_t object.
This function converts a sequence of wide characters from the array indirectly pointed to by src into a sequence of corresponding multibyte characters, beginning in the conversion state described by the object pointed to by ps.If dst is a not NULL pointer, the converted characters are then stored into the array pointed to by dst. Conversion continues up to and including a terminating null wide character, which is also stored.
Conversion stops earlier in two cases:
- When a code is reached that does not correspond to a valid multibyte character
- If dst is not a NULL pointer, when the next multibyte character would exceed the limit of len total bytes to be stored into the array pointed to by dst
Each conversion takes place as if by a call to the wcrtomb function.
If dst is not a NULL pointer, the pointer object pointed to by src is assigned either a NULL pointer, (if the conversion stopped because it reached a terminating null wide character) or the address just beyond the last wide character converted (if any). If conversion stopped because it reached a terminating null wide character, the resulting state described is the initial conversion state.
If the wcsrtombs function is called as a counting function, which means that dst is a NULL pointer, the value of the internal mbstate_t object will remain unchanged.
See also wcrtomb in this section.
x The number of bytes stored in the resulting array, not including the terminating null (if any). --1 Indicates an encoding error---a character that does not correspond to a valid multibyte character was encountered; errno is set to eilseq ; the conversion state is undefined.
Compares the characters in a wide-character string against a set of wide characters. The function returns the length of the first substring comprised entirely of characters in the set of wide characters.
#include <wchar.h>size_t wcsspn (const wchar_t *wstr1, const wchar_t *wstr2);
wstr1
A pointer to a null-terminated wide-character string. If this string is a null string, 0 is returned.wstr2
A pointer to a null-terminated wide-character string that contains the set of wide characters for which the function will search.
This function scans the wide characters in the wide-character string pointed to by wstr1 until it encounters a character not found in wstr2. The function returns the length of the first segment of wstr1 formed by characters found in wstr2.
x The length of the segment.
#include <stdlib.h> #include <stdio.h> #include <wchar.h> #include <string.h> /* This test sets up 2 strings, buffer and w_string. It then */ /* uses wcsspn() to calculate the maximum segment of w_string */ /* that consists entirely of characters from buffer. */ #define BUFF_SIZE 20 #define STRING_SIZE 50 main() { wchar_t buffer[BUFF_SIZE]; wchar_t w_string[STRING_SIZE]; size_t result; /* Initialize the buffer */ if (mbstowcs(buffer, "abcdefg", BUFF_SIZE) == -1) { perror("mbstowcs"); exit(EXIT_FAILURE); } /* Initialize the string */ if (mbstowcs(w_string, "abcedjklmabcjklabcdehjkl", STRING_SIZE) == -1) { perror("mbstowcs"); exit(EXIT_FAILURE); } /* Using wcsspn - work out the largest string in w_string that */ /* consists entirely of characters from buffer */ result = wcsspn(w_string, buffer); printf("Longest segment found in w_string is: %d", result); }
Running the example program produces the following result:
Longest segment found in w_string is: 5 |
Locates the first occurrence in the string pointed to by s1 of the sequence of wide characters in the string pointed to by s2.
#include <wchar.h>Function Variants This function also has variants named _wcsstr32 and _wcsstr64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 for more information on using pointer-size-specific functions.wchar_t *wcsstr (const wchar_t *s1, const wchar_t *s2);
s1, s2
Pointers to null-terminated, wide-character strings.
If s2 points to a wide-character string of zero length, the function returns s1.
x A pointer to the located string. NULL Indicates an error; the string was not found.
Converts a given wide-character string to a double-precision number.
#include <wchar.h>double wcstod (const wchar_t *nptr, wchar_t **endptr);
nptr
A pointer to the wide-character string to be converted to a double-precision number.endptr
The address of an object where the function can store the address of the first unrecognized wide character that terminates the scan. If endptr is a NULL pointer, the address of the first unrecognized wide character is not retained.
This function recognizes an optional sequence of white-space characters (as defined by iswspace ), then an optional plus or minus sign, then a sequence of digits optionally containing a radix character, then an optional letter (e or E) followed by an optionally signed integer. The first unrecognized character ends the conversion.The string is interpreted by the same rules used to interpret floating constants.
The radix character is defined in the program's current locale (category LC_NUMERIC).
This function returns the converted value. For wcstod , overflows are accounted for in the following manner:
- If the correct value causes an overflow, HUGE_VAL (with a plus or minus sign according to the sign of the value) is returned and errno is set to ERANGE.
- If the correct value causes an underflow, 0 is returned and errno is set to ERANGE.
If the string starts with an unrecognized wide character, *endptr is set to nptr and a 0 value is returned.
x The converted string. 0 Indicates the conversion could not be performed. The function sets errno to one of:
- EINVAL -- No conversion could be performed.
- ERANGE -- The value would cause an underflow.
- ENOMEM -- Not enough memory available for internal conversion buffer.
(+/ --)HUGE_VAL Indicates overflow. The function sets errno to ERANGE.
Locates text tokens in a given wide-character string.
#include <wchar.h>Function Variants This function also has variants named _wcstok32 and _wcstok64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 for more information on using pointer-size-specific functions.wchar_t *wcstok (wchar_t *ws1, const wchar_t *ws2); (XPG4)
wchar_t *wcstok (wchar_t *ws1, const wchar_t *ws2, wchar_t **ptr); (ISO C)
ws1
A pointer to a wide-character string containing 0 or more text tokens.ws2
A pointer to a separator string consisting of one or more wide characters. The separator string can differ from call to call.ptr
ISO C Standard only. Used only when ws1 is NULL, ptr is a caller-provided wchar_t pointer into which wcstok stores information necessary for it to continue scanning the same wide-character string.
A sequence of calls to wcstok breaks the wide-character string pointed to by ws1 into a sequence of tokens, each of which is delimited by a wide character from the wide-character string pointed to by ws2.The wcstok function keeps track of its position in the wide-character string between calls and, as successive calls are made, the function works through the wide-character string, identifying the text token following the one identified by the previous call.
Tokens in ws1 are delimited by null characters that wcstok inserts into ws1. Therefore, ws1 cannot be a const object.
The following sections describe differences between the XPG4 Standard and ISO C Standard interface to wcstok .
The first call to the wcstok function searches the wide-character string for the first character that is not found in the separator string pointed to by ws2. The first call returns a pointer to the first wide character in the first token and writes a null wide character into ws1 immediately following the returned token.
Subsequent calls to wcstok search for a wide character that is in the separator string pointed to by ws2. Each subsequent call (with the value of the first argument remaining NULL) returns a pointer to the next token in the string originally pointed to by ws1. When no tokens remain in the string, wcstok returns a NULL pointer.
For the first call in the sequence, ws1 points to a wide-character string. In subsequent calls for the same string, ws1 is NULL. When ws1 is NULL, the value pointed to by ptr matches that stored by the previous call for the same wide-character string. Otherwise, the value pointed to by ptr is ignored.
The first call in the sequence searches the wide-character string pointed to by ws1 for the first wide character that is not contained in the current separator wide-character string pointed to by ws2. If no such wide character is found, then there are no tokens in the wide-character string pointed to by ws1, and wcstok returns a NULL pointer.
The wcstok function then searches from there for a wide character that is contained in the current separator wide-character string. If no such wide character is found, the current token extends to the end of the wide-character string pointed to by ws1, and subsequent searches in the same wide-character string for a token return a NULL pointer. If such a wide character is found, it is overwritten by a null wide character, which terminates the current token.
In all cases, wcstok stores sufficient information in the pointer pointed to by ptr so that subsequent calls with a NULL pointer for ws1 and the unmodified pointer value for ptr start searching just past the element overwritten by a null wide character (if any).
x A pointer to the first character of a token. NULL Indicates that no token was found.
| #1 |
|---|
/* XPG4 version of wcstok call */
#include <wchar.h>
#include <string.h>
#include <stdio.h>
main()
{
wchar_t str[] = L"...ab..cd,,ef.hi";
printf("|%S|\n", wcstok(str, L"."));
printf("|%S|\n", wcstok(NULL, L","));
printf("|%S|\n", wcstok(NULL, L",."));
printf("|%S|\n", wcstok(NULL, L",."));
}
|
| #2 |
|---|
/* ISO C version of wcstok call */
#include <wchar.h>
#include <string.h>
#include <stdio.h>
main()
{
wchar_t str[] = L"...ab..cd,,ef.hi";
wchar_t *savptr = NULL;
printf("|%S|\n", wcstok(str, L".", &savptr));
printf("|%S|\n", wcstok(NULL, L",", &savptr));
printf("|%S|\n", wcstok(NULL, L",.", &savptr));
printf("|%S|\n", wcstok(NULL, L",.", &savptr));
}
|
Running this example produces the following results:
$ $ RUN WCSTOK_EXAMPLE |ab| |.cd| |ef| |hi| $ |
Converts a wide-character string in a specified base to a long integer value.
#include <wchar.h>Function Variants This function also has variants named _wcstol32 and _wcstol64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 for more information on using pointer-size-specific functions.long int wcstol (const wchar_t *nptr, wchar_t **endptr, int base);
nptr
A pointer to the wide-character string to be converted to a long integer.endptr
The address of an object where the function can store a pointer to the first unrecognized character encountered in the conversion process (the character that follows the last character processed in the string being converted). If endptr is a NULL pointer, the address of the first unrecognized character is not retained.base
The value, 2 through 36, to use as the base for the conversion.If base is 16, leading zeros after the optional sign are ignored, and 0x or 0X is ignored.
If base is 0, the sequence of characters is interpreted by the same rules used to interpret an integer constant---After the optional sign:
- A leading 0 indicates octal conversion.
- A leading 0x or 0X indicates hexadecimal conversion.
- Any other combination of leading characters indicates decimal conversion.
This function recognizes strings in various formats, depending on the value of the base. This function ignores any leading white-space characters (as defined by the iswspace function) in the given string. It recognizes an optional plus or minus sign, then a sequence of digits or letters that can represent an integer constant according to the value of the base. The first unrecognized character ends the conversion.
x The converted value. 0 Indicates that the string starts with an unrecognized wide character or that the value for base is invalid. If the string starts with an unrecognized wide character, * endptr is set to nptr. The function sets errno to EINVAL. LONG_MAX or LONG_MIN Indicates that the converted value would cause a positive or negative overflow, respectively. The function sets errno to ERANGE.
| Previous | Next | Contents | Index |
|
