| Previous | Contents | Index |
Concatenates two wide-character strings.
#include <wchar.h>Function Variants The wcscat function has variants named _wcscat32 and _wcscat64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information on using pointer-size-specific functions.wchar_t *wcscat (wchar_t *wstr_1, const wchar_t *wstr_2);
wstr_1, wstr_2
Pointers to null-terminated wide-character strings.
The wcscat function appends the wide-character string wstr_2, including the terminating null character, to the end of wstr_1.See also wcsncat .
x The first argument, wstr_1, which is assumed to be large enough to hold the concatenated result.
#include <stdlib.h> #include <stdio.h> #include <wchar.h> #include <string.h> /* This program concatenates two wide-character strings using */ /* the wcscat function, and then manually compares the result */ /* to the expected result */ #define S1LENGTH 10 #define S2LENGTH 8 main() { int i; wchar_t s1buf[S1LENGTH + S2LENGTH]; wchar_t s2buf[S2LENGTH]; wchar_t test1[S1LENGTH + S2LENGTH]; /* Initialize the three wide-character strings */ if (mbstowcs(s1buf, "abcmnexyz", S1LENGTH) == (size_t)-1) { perror("mbstowcs"); exit(EXIT_FAILURE); } if (mbstowcs(s2buf, " orthis", S2LENGTH) == (size_t)-1) { perror("mbstowcs"); exit(EXIT_FAILURE); } if (mbstowcs(test1, "abcmnexyz orthis", S1LENGTH + S2LENGTH) == (size_t)-1) { perror("mbstowcs"); exit(EXIT_FAILURE); } /* Concatenate s1buf with s2buf, placing the result */ /* into * s1buf. Then compare s1buf with the expected */ /* result in test1. */ wcscat(s1buf, s2buf); for (i = 0; i < S1LENGTH + S2LENGTH - 2; i++) { /* Check that each character is correct */ if (test1[i] != s1buf[i]) { printf("Error in wcscat\n"); exit(EXIT_FAILURE); } } printf("Concatenated string: <%S>\n", s1buf); }Running the example produces the following result:
Concatenated string: <abcmnexyz orthis>
Scans for a wide character in a specifed wide-character string.
#include <wchar.h>Function Variants The wcschr function has variants named _wcschr32 and _wcschr64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information on using pointer-size-specific functions.wchar_t *wcschr (const wchar_t *wstr, wchar_t wc);
wstr
A pointer to a null-terminated wide-character string.wc
A character of type wchar_t .
The wcschr function returns the address of the first occurrence of a specified wide character in a null-terminated wide-character string. The terminating null character is considered to be part of the string.See also wcsrchr .
x The address of the first 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 main() { int i; wchar_t s1buf[BUFF_SIZE]; wchar_t *status; /* Initialize the buffer */ if (mbstowcs(s1buf, "abcdefghijkl lkjihgfedcba", BUFF_SIZE) == (size_t)-1) { perror("mbstowcs"); exit(EXIT_FAILURE); } /* This program checks the wcschr function by incrementally */ /* going through a string that ascends to the middle and */ /* then descends towards the end. */ for (i = 0; (s1buf[i] != '\0') && (s1buf[i] != ' '); i++) { status = wcschr(s1buf, s1buf[i]); /* Check for pointer to leftmost character - test 1. */ if (status != &s1buf[i]) { printf("Error in wcschr\n"); exit(EXIT_FAILURE); } } printf("Program completed successfully\n"); }When this example program is run, it produces the following result:
Program completed successfully
Compares two wide-character strings. It returns an integer that indicates if the strings are different, and how they differ.
#include <wchar.h>int wcscmp (const wchar_t *wstr_1, const wchar_t *wstr_2);
wstr_1, wstr_2
Pointers to null-terminated wide-character strings.
The wcscmp function compares the wide characters in wstr_1 with those in wstr_2. If the characters differ, the function returns:
- An integer less than 0, if the codepoint of the first differing character in wstr_1 is less than the codepoint of the corresponding character in wstr_2
- An integer greater than 0, if the codepoint of the first differing character in wstr_1 is greater than the codepoint of the corresponding character in wstr_2
If the wide-characters strings are identical, the function returns 0.
Unlike the wcscoll function, the wcscmp function compares the string based on the binary value of each wide character.
See also wcsncmp .
< 0 Indicates that wstr_1 is less than wstr_2. = 0 Indicates that wstr_1 equals wstr_2. > 0 Indicates that wstr_1 is greater than wstr_2.
Compares two wide-character strings and returns an integer that indicates if the strings differ, and how they differ. The function uses the collating information in the LC_COLLATE category of the current locale to determine how the comparison is performed.
#include <wchar.h>int wcscoll (const wchar_t *ws1, const wchar_t *ws2);
ws1, ws2
Pointers to wide-character strings.
The wcscoll function, unlike wcscmp , compares two strings in a locale-dependent manner. Because no value is reserved for error indication, the application must check for one by setting errno to 0 before the function call and testing it after the call.See also wcsxfrm .
< 0 Indicates that ws1 is less than ws2. 0 Indicates that the strings are equal. > 0 Indicates that ws1 is greater than ws2.
Copies the wide-character string source, including the terminating null character, into dest.
#include <wchar.h>Function Variants The wcscpy function has variants named _wcscpy32 and _wcscpy64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information on using pointer-size-specific functions.wchar_t *wcscpy (wchar_t *dest, const wchar_t *source);
dest
Pointer to the null-terminated wide-character destination string.source
Pointer to the null-terminated wide-character source string.
The wcscpy function copies source into dest, and stops after copying source's null character. If copying takes place between two ovelapping strings, the behavior is undefined.See also wcsncpy .
x The address of source.
Compares the characters in a wide-character string against a set of wide characters. The function returns the length of the initial substring that is comprised entirely of characters that are not in the set of wide characters.
#include <wchar.h>size_t wcscspn (const wchar_t *wstr1, const wchar_t *wstr2);
wstr1
A pointer to a null-terminated wide-character string. If this 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.
The wcscspn function scans the wide characters in the string pointed to by wstr1 until it encounters a character found in wstr2. The function returns the length of the initial segment of wstr1 that is formed by characters not 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, and */ /* then uses wcscspn() to calculate the maximum segment */ /* of w_string, which consists entirely of characters */ /* NOT 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) == (size_t)-1) { perror("mbstowcs"); exit(EXIT_FAILURE); } /* Initialize the string */ if (mbstowcs(w_string, "jklmabcjklabcdehjklmno", STRING_SIZE) == (size_t)-1) { perror("mbstowcs"); exit(EXIT_FAILURE); } /* Using wcscspn - work out the largest string in w_string */ /* which consists entirely of characters NOT from buffer */ result = wcscspn(w_string, buffer); printf("Longest segment NOT found in w_string is: %d", result); }
Running the example program produces the following result:
Longest segment NOT found in w_string is: 4 |
Uses date and time information stored in a tm structure to create a wide-character output string. The format of the output string is controlled by a format string.
#include <wchar.h>Function Variants Compiling with the _DECC_V4_SOURCE and _VMS_V6_SOURCE feature-test macros defined enables a local-time-based entry point to the wcsftime function that is equivalent to the behavior before OpenVMS Version 7.0.size_t wcsftime (wchar_t *wcs, size_t maxsize, const char *format, const struct tm *timeptr); (XPG4)
size_t wcsftime (wchar_t *wcs, size_t maxsize, const wchar_t *format, const struct tm *timeptr); (ISO C)
wcs
A pointer to the resultant wide-character string.maxsize
The maximum number of wide characters to be stored in the resultant string.format
A pointer to the string that controls the format of the output string. For the XPG4 interface, this argument is a pointer to a constant character string. For the ISO C interface, it is a pointer to a constant wide-character string.timeptr
A pointer to the local time structure. The tm structure is defined in the <time.h> header file.
The wcsftime function uses data in the structure pointed to by timeptr to create the wide-character string pointed to by wcs. A maximum of maxsize wide characters is copied to wcs.The format string consists of zero or more conversion specifications and ordinary characters. All ordinary characters (including the terminating null character) are copied unchanged into the output string. A conversion specification defines how data in the tm structure is formatted in the output string.
A conversion specification consists of a percent (%) character followed by one or more optional characters (see Table REF-13), and ending with a conversion specifier (see Table REF-14). If any of the optional characters listed in Table REF-13 are specified, they must appear in the order shown in the table.
Table REF-13 Optional Elements of wcsftime Conversion Specifications Element Meaning -- Optional with the field width to specify that the field is left-justified and padded with spaces. This cannot be used with the 0 element. 0 Optional with the field width to specify that the field is right-justified and padded with zeros. This cannot be used with the -- element. field width A decimal integer that specifies the maximum field width .precision A decimal integer that specifies the precision of data in a field. For the d, H, I, j, m, M, o, S, U, w, W, y, and Y conversion specifiers, the precision specifier is the minimum number of digits to appear in the field. If the conversion specification has fewer digits than that specified by the precision, leading zeros are added.
For the a, A, b, B, c, D, E, h, n, N, p, r, t, T, x, X, Z, and % conversion specifiers, the precision specifier is the maximum number of wide characters to appear in the field. If the conversion specification has more characters than that specified by the the precision, characters are truncated on the right.
The default precision for the d, H, I, m, M, o, S, U, w, W, y, and Y conversion specifiers is 2, and the default precision for the j conversion specifier is 3.
Note that the list of optional elements of conversion specifications from Table REF-13 are HP extensions to the XPG4 specification.
Table REF-14 lists the conversion specifiers. The wcsftime function uses fields in the LC_TIME category of the program's current locale to provide a value. For example, if %B is specified, the function accesses the mon field in LC_TIME to find the full month name for the month specified in the tm structure. The result of using invalid conversion specifiers is undefined.
Table REF-14 wcsftime 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. C The century number (the year divided by 100 and truncated to an integer) as a decimal number (00 -- 99). d The day of the month as a decimal number (01 -- 31). D Same as %m/%d/%y . e The day of the month as a decimal number (1 -- 31) in a 2-digit field with the leading space character fill. Ec The locale's alternative date and time representation. EC The name of the base year (period) in the locale's alternative representation. Ex The locale's alternative date representation. Ey The offset from the base year ( %EC ) in the locale's alternative representation. EY The locale's full alternative year representation. h Same as %b . 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). n The new-line character. Od The day of the month using the locale's alternative numeric symbols. Oe The date of the month using the locale's alternative numeric symbols. OH The hour (24-hour clock) using the locale's alternative numeric symbols. OI The hour (12-hour clock) using the locale's alternative numeric symbols. Om The month using the locale's alternative numeric symbols. OM The minutes using the locale's alternative numeric symbols. OS The seconds using the locale's alternative numeric symbols. Ou The weekday as a number in the locale's alternative representation (Monday=1). OU The week number of the year (Sunday as the first day of the week) using the locale's alternative numeric symbols. OV The week number of the year (Monday as the first day of the week) as a decimal number (01 --53) using the locale's alterntative numeric symbols. If the week containing January 1 has four or more days in the new year, it is considered as week 1. Otherwise, it is considered as week 53 of the previous year, and the next week is week 1. Ow The weekday as a number (Sunday=0) using the locale's alternative numeric symbols. OW The week number of the year (Monday as the first day of the week) using the locale's alternative numeric symbols. Oy The year without the century using the locale's alternative numeric symbols. p The locale's equivalent of the AM/PM designations associated with a 12-hour clock. r The time in AM/PM notation. R The time in 24-hour notation ( %H:%M ). S The second as a decimal number (00 -- 61). t The tab character. T The time ( %H:%M:%S ). u The weekday as a decimal number between 1 and 7 (Monday=1). U The week number of the year (the first Sunday as the first day of week 1) as a decimal number (00 -- 53). V The week number of the year (Monday as the first day of the week) as a decimal number (00 -- 53). If the week containing January 1 has four or more days in the new year, it is considered as week 1. Otherwise, it is considered as week 53 of the previous year, and the next week is week 1. 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 Time-zone name or abbreviation. If time-zone information is not available, no character is output. % Literal % character.
x The number of wide characters placed into the array pointed to by wcs, not including the terminating null character. 0 Indicates an error occurred. The contents of the array are indeterminate.
Previous Next Contents Index