HP C
Run-Time Library Reference Manual for OpenVMS Systems


Previous Contents Index


 /* Exercise the wcsftime formatting routine.             */ 
 /* NOTE: the format string is an "L" (or wide character) */ 
 /*       string indicating that this call is NOT in      */ 
 /*       the XPG4 format, but rather in ISO C format.    */ 
 
#include <stdlib.h> 
#include <stdio.h> 
#include <time.h> 
#include <wchar.h> 
#include <locale.h> 
#include <errno.h> 
 
#define NUM_OF_DATES  7 
#define BUF_SIZE 256 
 
 /* This program formats a number of different dates, once using the   */ 
 /* C locale and then using the fr_FR.ISO8859-1 locale.  Date and time */ 
 /* formatting is done using wcsftime().                               */ 
 
main() 
 
{ 
  int count, 
      i; 
  wchar_t buffer[BUF_SIZE]; 
  struct tm *tm_ptr; 
  time_t time_list[NUM_OF_DATES] = 
  {500, 68200000, 694223999, 
   694224000, 704900000, 705000000, 
   705900000}; 
 
  /* Display dates using the C locale */ 
  printf("\nUsing the C locale:\n\n"); 
 
  setlocale(LC_ALL, "C"); 
 
  for (i = 0; i < NUM_OF_DATES; i++) { 
      /* Convert to a tm structure */ 
      tm_ptr = localtime(&time_list[i]); 
 
      /* Format the date and time */ 
      count = wcsftime(buffer, BUF_SIZE, L"Date: %A %d %B %Y%nTime: %T%n%n", 
                      tm_ptr); 
      if (count == 0) { 
          perror("wcsftime"); 
          exit(EXIT_FAILURE); 
      } 
 
      /* Print the result */ 
      printf("%S", buffer); 
  } 
 
  /* Display dates using the fr_FR.ISO8859-1 locale */ 
  printf("\nUsing the fr_FR.ISO8859-1 locale:\n\n"); 
 
  setlocale(LC_ALL, "fr_FR.ISO8859-1"); 
 
  for (i = 0; i < NUM_OF_DATES; i++) { 
      /* Convert to a tm structure */ 
      tm_ptr = localtime(&time_list[i]); 
 
      /* Format the date and time */ 
      count = wcsftime(buffer, BUF_SIZE, L"Date: %A %d %B %Y%nTime: %T%n%n", 
                       tm_ptr); 
      if (count == 0) { 
          perror("wcsftime"); 
          exit(EXIT_FAILURE); 
      } 
 
      /* Print the result */ 
      printf("%S", buffer); 
  } 
} 

Running the example program produces the following result:


Using the C locale: 
 
Date: Thursday 01 January 1970 
Time: 00:08:20 
 
Date: Tuesday 29 February 1972 
Time: 08:26:40 
 
Date: Tuesday 31 December 1991 
Time: 23:59:59 
 
Date: Wednesday 01 January 1992 
Time: 00:00:00 
 
Date: Sunday 03 May 1992 
Time: 13:33:20 
 
Date: Monday 04 May 1992 
Time: 17:20:00 
 
Date: Friday 15 May 1992 
Time: 03:20:00 
 
 
Using the fr_FR.ISO8859-1 locale: 
 
Date: jeudi 01 janvier 1970 
Time: 00:08:20 
 
Date: mardi 29 février 1972 
Time: 08:26:40 
 
Date: mardi 31 décembre 1991 
Time: 23:59:59 
 
Date: mercredi 01 janvier 1992 
Time: 00:00:00 
 
Date: dimanche 03 mai 1992 
Time: 13:33:20 
 
Date: lundi 04 mai 1992 
Time: 17:20:00 
 
Date: vendredi 15 mai 1992 
Time: 03:20:00 


wcslen

Returns the number of wide characters in a wide-character string. The returned length does not include the terminating null character.

Format

#include <wchar.h>

size_t wcslen (const wchar_t *wstr);


Argument

wstr

A pointer to a null-terminated wide-character string.

Return Value

x The length of the wide-character string, excluding the terminating null wide character.

wcsncat

Concatenates a counted number of wide-characters from one string to another.

Format

#include <wchar.h>

wchar_t *wcsncat (wchar_t *wstr_1, const wchar_t *wstr_2, size_t maxchar);

Function Variants The wcsncat function has variants named _wcsncat32 and _wcsncat64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.9 for more information on using pointer-size-specific functions.

Arguments

wstr_1, wstr_2

Pointers to null-terminated wide-character strings.

maxchar

The maximum number of wide characters from wstr_2 that are copied to wstr_1. If maxchar is 0, no characters are copied from wstr_2.

Description

The wcsncat function appends wide characters from the wide-character string wstr_2 to the end of wstr_1, up to a maximum of maxchar characters. A terminating null wide character is always appended to the result of the wcsncat function. Therefore, the maximum number of wide characters that can end up in wstr_1 is wcslen (wstr_1) + maxchar + 1).

See also wcscat .


Return Value

x The first argument, wstr_1, which is assumed to be large enough to hold the concatenated result.

Example


#include <stdlib.h> 
#include <stdio.h> 
#include <wchar.h> 
#include <string.h> 
 
/* This program concatenates two wide-character strings using   */ 
/* the wcsncat function, and then manually compares the result  */ 
/* to the expected result                                       */ 
 
#define S1LENGTH 10 
#define S2LENGTH 8 
#define SIZE     3 
 
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 + SIZE) 
 
        == (size_t)-1) { 
 
        perror("mbstowcs"); 
        exit(EXIT_FAILURE); 
    } 
 
/* Concatenate s1buf with SIZE characters from s2buf, */ 
/* placing the result into s1buf. Then compare s1buf  */ 
/* with the expected result in test1.                 */ 
 
    wcsncat(s1buf, s2buf, SIZE); 
 
    for (i = 0; i <= S1LENGTH + SIZE - 2; i++) { 
        /* Check that each character is correct */ 
        if (test1[i] != s1buf[i]) { 
            printf("Error in wcsncat\n"); 
            exit(EXIT_FAILURE); 
        } 
                        
    } 
 
    printf("Concatenated string: <%S>\n", s1buf); 
} 

Running the example produces the following result:


Concatenated string: <abcmnexyz or> 


wcsncmp

Compares not more than maxchar characters of two wide-character strings. It returns an integer that indicates if the strings are different, and how they differ.

Format

#include <wchar.h>

int wcsncmp (const wchar_t *wstr_1, const wchar_t *wstr_2, size_t maxchar);


Arguments

wstr_1, wstr_2

Pointers to null-terminated wide-character strings.

maxchar

The maximum number of characters to search in both wstr_1 and wstr_2. If maxchar is 0, no comparison is performed and 0 is returned (the strings are considered equal).

Description

The strings are compared until a null character is encountered, the strings differ, or maxchar is reached. If characters differ, wcsncmp returns:

If no differences are found after comparing maxchar characters, the function returns 0.

See also wcscmp .


Return Values

< 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.

wcsncpy

Copies wide characters from source into dest. The function copies up to a maximum of maxchar characters.

Format

#include <wchar.h>

wchar_t *wcsncpy (wchar_t *dest, const wchar_t *source, size_t maxchar);

Function Variants The wcsncpy function has variants named _wcsncpy32 and _wcsncpy64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.9 for more information on using pointer-size-specific functions.

Arguments

dest

Pointer to the null-terminated wide-character destination string.

source

Pointer to the null-terminated wide-character source string.

maxchar

The maximum number of wide characters to copy from source to dest.

Description

The wcsncpy function copies no more than maxchar characters from source to dest. If source contains less than maxchar characters, null characters are added to dest until maxchar characters have been written to dest.

If source contains maxchar or more characters, as many characters as possible are copied to dest. The null terminator of source is not copied to dest.

See also wcscpy .


Return Value

x The address of dest.

wcspbrk

Searches a wide-character string for the first occurrence of one of a specified set of wide characters.

Format

#include <wchar.h>

wchar_t *wcspbrk (const wchar_t *wstr, const wchar_t *charset);

Function Variants The wcspbrk function has variants named _wcspbrk32 and _wcspbrk64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.9 for more information on using pointer-size-specific functions.

Arguments

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.

Description

The wcspbrk 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.

Return Values

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.

wcsrchr

Scans for the last occurrence of a wide character in a given string.

Format

#include <wchar.h>

wchar_t *wcsrchr (const wchar_t *wstr, wchar_t wc);

Function Variants The wcsrchr function has variants named _wcsrchr32 and _wcsrchr64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.9 for more information on using pointer-size-specific functions.

Arguments

wstr

A pointer to a null-terminated wide-character string.

wc

A character of type wchar_t .

Description

The wcsrchr 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 .


Return Values

x The address of the last occurrence of the specified wide character.
NULL Indicates that the wide character does not occur in the string.

Example


#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) 
 
        == (size_t)-1) { 
 
        perror("mbstowcs"); 
        exit(EXIT_FAILURE); 
    } 
 
    /* Initialize the string to be searched for */ 
 
 
    if (mbstowcs(w_string, "hijkl", STRING_SIZE) == (size_t)-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] 


wcsrtombs

Converts a sequence of wide characters into a sequence of corresponding multibyte characters.

Format

#include <wchar.h>

size_t wcsrtombs (char *dst, const wchar_t **src, size_t len, mbstate_t *ps);

Function Variants The wcsrtombs function has variants named _wcsrtombs32 and _wcsrtombs64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.9 for more information on using pointer-size-specific functions.

Arguments

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. mbstate_t is an opaque datatype intended to keep the conversion state for the state-dependent codesets.

Description

The wcsrtombs 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 a 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:

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 .


Return Values

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.

wcsspn

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.

Format

#include <wchar.h>

size_t wcsspn (const wchar_t *wstr1, const wchar_t *wstr2);


Arguments

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.

Description

The wcsspn 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.

Return Value

x The length of the segment.

Example


#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) == (size_t)-1) { 
 
        perror("mbstowcs"); 
        exit(EXIT_FAILURE); 
    } 
 
    /* Initialize the string */ 
                                   
    if (mbstowcs(w_string, "abcedjklmabcjklabcdehjkl", STRING_SIZE) 
 
        == (size_t)-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 


wcsstr

Locates the first occurrence in the string pointed to by s1 of the sequence of wide characters in the string pointed to by s2.

Format

#include <wchar.h>

wchar_t *wcsstr (const wchar_t *s1, const wchar_t *s2);

Function Variants The wcsstr function has variants named _wcsstr32 and _wcsstr64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.9 for more information on using pointer-size-specific functions.

Arguments

s1, s2

Pointers to null-terminated, wide-character strings.

Description

If s2 points to a wide-character string of 0 length, the wcsstr function returns s1.

Return Values

x A pointer to the located string.
NULL Indicates an error; the string was not found.

wcstod

Converts a given wide-character string to a double-precision number.

Format

#include <wchar.h>

double wcstod (const wchar_t *nptr, wchar_t **endptr);


Arguments

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.

Description

The wcstod 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 string starts with an unrecognized wide character, *endptr is set to nptr and a 0 value is returned.


Return Values

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 Overflow occurred; errno is set to ERANGE.


Previous Next Contents Index