HP C
Run-Time Library Reference Manual for OpenVMS Systems
Previous Contents Index

wcstok

Locates text tokens in a given wide-character string.

Format

#include <wchar.h>

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)

Function Variants The wcstok function has variants named _wcstok32 and _wcstok64 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

ws1

A pointer to a wide-character string containing zero 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.

Description

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 .

XPG4 Standard Behavior

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.

ISO C Standard Behavior

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

Return Values

x A pointer to the first character of a token.
NULL Indicates that no token was found.

Examples

#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|
$

wcstol

Converts a wide-character string in a specified base to a long integer value.

Format

#include <wchar.h>

long int wcstol (const wchar_t *nptr, wchar_t **endptr, int base);

Function Variants The wcstol function has variants named _wcstol32 and _wcstol64 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

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:

Description

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

Return Values

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.

wcstombs

Converts a sequence of wide-character codes to a sequence of multibyte characters.

Format

#include <stdlib.h>

size_t wcstombs (char *s, const wchar_t *pwcs, size_t n);

Arguments

s

A pointer to the array containing the resulting multibyte characters.

pwcs

A pointer to the array containing the sequence of wide-character codes.

n

The maximum number of bytes to be stored in the array pointed to by s.

Description

The wcstombs function converts a sequence of codes corresponding to multibyte characters from the array pointed to by pwcs to a sequence of multibyte characters that are stored into the array pointed to by s, up to a maximum of n bytes. The value returned is equal to the number of characters converted or a - 1 if an error occurred.

This function is affected by the LC_CTYPE category of the program's current locale.

If s is NULL, this function call is a counting operation and n is ignored.

See also wctomb .

Return Values

x The number of bytes stored in s, not including the null terminating byte. If s is NULL, wcstombs returns the number of bytes required for the multibyte character array.
( size_t ) - 1 Indicates an error occurred. The function sets errno to EILSEQ -- invalid character sequence, or a wide-character code does not correspond to a valid character.

wcstoul

Converts the initial portion of the wide-character string pointed to by nptr to an unsigned long integer.

Format

#include <wchar.h>

unsigned long int wcstoul (const wchar_t *nptr, wchar_t **endptr, int base);

Function Variants The wcstoul function has variants named _wcstoul32 and _wcstoul64 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

nptr

A pointer to the wide-character string to be converted to an unsigned long .

endptr

The address of an object where the function can store the address of the first unrecognized character encountered in the conversion process (the character that follows the last character 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, and any other combination of leading characters indicates decimal conversion.

Description

The wcstoul function recognizes strings in various formats, depending on the value of the base. It ignores any leading white-space characters (as defined by the iswspace function) in the string. It recognizes an optional plus or minus sign, then a sequence of digits or letters that may represent an integer constant according to the value of the base. The first unrecognized wide character ends the conversion.

Return Values

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.
ULONG_MAX Indicates that the converted value would cause an overflow. The function sets errno to ERANGE.

Example


#include <stdlib.h> 
#include <stdio.h> 
#include <wchar.h> 
#include <errno.h> 
#include <limits.h> 
 
/* This test calls wcstoul() to convert a string to an     */ 
/* unsigned long integer. wcstoul outputs the resulting    */ 
/* integer and any characters that could not be converted. */ 
 
#define MAX_STRING 128 
 
main() 
{ 
 
    int base = 10, 
        errno; 
    char *input_string = "1234.56"; 
    wchar_t string_array[MAX_STRING], 
           *ptr; 
    size_t size; 
    unsigned long int val; 
    printf("base = [%d]\n", base); 
    printf("String to convert = %s\n", input_string); 
    if ((size = mbstowcs(string_array, input_string, MAX_STRING)) == 
 
        (size_t)-1) { 
 
        perror("mbstowcs"); 
        exit(EXIT_FAILURE); 
    } 
    printf("wchar_t string is = [%S]\n", string_array); 
 
    errno = 0; 
    val = wcstoul(string_array, &ptr, base); 
    if (errno == 0) { 
printf("returned unsigned long int from wcstoul = [%u]\n", val); 
      printf("wide char terminating scan(ptr) = [%S]\n\n", ptr); 
    } 
    if (errno == ERANGE) { 
        perror("error value is :"); 
        printf("ULONG_MAX = [%u]\n", ULONG_MAX); 
        printf("wcstoul failed, val = [%d]\n\n", val); 
    } 
 
}

Running the example program produces the following result: 


base = [10] 
String to convert = 1234.56 
wchar_t string is = [1234.56] 
returned unsigned long int from wcstoul = [1234] 
wide char terminating scan(ptr) = [.56]

wcswcs

Locates the first occurrence in the string pointed to by wstr1 of the sequence of wide characters in the string pointed to by wstr2.

Format

#include <wchar.h>

wchar_t *wcswcs (const wchar_t *wstr1, const wchar_t *wstr2);

Function Variants The wcswcs function has variants named _wcswcs32 and _wcswcs64 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

wstr1, wstr2

Pointers to null-terminated wide-character strings.

Return Values

Pointer A pointer to the located wide-character string.
NULL Indicates that the wide-character string was not found.

Example


#include <stdlib.h> 
#include <stdio.h> 
#include <wchar.h> 
 
/* This test uses wcswcs() to find the occurrence of each */ 
/* subwide-character string, string1 and string2, within  */ 
/* the main wide-character string, lookin.                */ 
 
#define BUF_SIZE 50 
 
main() 
{ 
  static char lookin[] = "that this is a test was at the end"; 
 
  char string1[] = "this", 
       string2[] = "the end"; 
 
  wchar_t buffer[BUF_SIZE], 
          input_buffer[BUF_SIZE]; 
 
  /* Convert lookin to wide-character format.         */ 
  /* Buffer and print it out.                         */ 
 
 
  if (mbstowcs(buffer, lookin, BUF_SIZE) == (size_t)-1) { 
 
      perror("mbstowcs"); 
      exit(EXIT_FAILURE); 
  } 
 
  printf("Buffer to look in: %S\n", buffer); 
 
  /* Convert string1 to wide-character format and use */ 
  /* wcswcs() to locate it within buffer              */ 
 
 
  if (mbstowcs(input_buffer, string1, BUF_SIZE) == (size_t)-1) { 
 
      perror("mbstowcs"); 
      exit(EXIT_FAILURE); 
  } 
 
  printf("this: %S\n", wcswcs(buffer, input_buffer)); 
 
  /* Convert string2 to wide-character format and use */ 
  /* wcswcs() to locate it within buffer              */ 
 
 
  if (mbstowcs(input_buffer, string2, BUF_SIZE) == (size_t)-1) { 
 
      perror("mbstowcs"); 
      exit(EXIT_FAILURE); 
  } 
  printf("the end: %S\n", wcswcs(buffer, input_buffer)); 
 
  exit(1); 
}

Running this example produces the following results: 


Buffer to look in: that this is a test was at the end 
this: this is a test was at the end 
the end: the end

wcswidth

Determines the number of printing positions on a display device that are required for a wide-character string.

Format

#include <wchar.h>

int wcswidth (const wchar_t *pwcs, size_t n);

Arguments

pwcs

A pointer to a wide-character string.

n

The maximum number of characters in the string.

Description

The wcswidth function returns the number of printing positions required to display the first n characters of the string pointed to by pwcs. If there are less than n wide characters in the string, the function returns the number of positions required for the whole string.

Return Values

x The number of printing positions required.
0 If pwcs is a null character.
- 1 Indicates that one (or more) of the wide characters in the string pointed to by pwcs is not a printable character.

wcsxfrm

Changes a wide-character string such that the changed string can be passed to the wcscmp function and produce the same result as passing the unchanged string to the wcscoll function.

Format

#include <wchar.h>

size_t wcsxfrm (wchar_t *ws1, const wchar_t *ws2, size_t maxchar);

Arguments

ws1, ws2

Pointers to wide-character strings.

maxchar

The maximum number of wide characters, including the null wide-character terminator, allowed to be stored in s1.

Description

The wcsxfrm function transforms the string pointed to by ws2 and stores the resulting string in the array pointed to by ws1. No more than maxchar wide characters, including the null wide terminator, are placed into the array pointed to by ws1.

If the value of maxchar is less than the required size to store the transformed string (including the terminating null), the contents of the array pointed to by ws1 is indeterminate. In such a case, the function returns the size of the transformed string.

If maxchar is 0, then, ws1 is allowed to be a NULL pointer, and the function returns the required size of the ws1 array before making the transformation.

The wide-character string comparison functions, wcscoll and wcscmp , can produce different results given the same two wide-character strings to compare. This is because wcscmp does a straightforward comparison of the code point values of the characters in the strings, whereas wcscoll uses the locale information to do the comparison. Depending on the locale, the wcscoll comparison can be a multipass operation, which is slower than wcscmp .

The wcsxfrm function transforms wide-character strings in such a way that if you pass two transformed strings to the wcscmp function, the result is the same as passing the two original strings to the wcscoll function. The wcsxfrm function is useful in applications that need to do a large number of comparisons on the same wide-character strings using wcscoll . In this case, it may be more efficient (depending on the locale) to transform the strings once using wcsxfrm and then use the wcscmp function to do comparisons.

Return Values

x Length of the resulting string pointed to by ws1, not including the terminating null character.
( size_t ) - 1 Indicates that an error occurred. The function sets errno to EINVAL -- The string pointed to by ws2 contains characters outside the domain of the collating sequence.

Example


#include <wchar.h> 
#include <stdio.h> 
#include <stdlib.h> 
#include <locale.h> 
 
 /* This program verifies that two transformed strings,    */ 
 /* when passed through wcsxfrm and then compared, provide */ 
 /* the same result as if passed through wcscoll without   */ 
 /* any transformation.                                    */ 
 
#define  BUFF_SIZE  20 
 
main() 
{ 
    wchar_t w_string1[BUFF_SIZE]; 
    wchar_t w_string2[BUFF_SIZE]; 
    wchar_t w_string3[BUFF_SIZE]; 
    wchar_t w_string4[BUFF_SIZE]; 
    int errno; 
    int coll_result; 
    int wcscmp_result; 
    size_t wcsxfrm_result1; 
    size_t wcsxfrm_result2; 
 
    /* setlocale to French locale */ 
 
    if (setlocale(LC_ALL, "fr_FR.ISO8859-1") == NULL) { 
        perror("setlocale"); 
        exit(EXIT_FAILURE); 
    } 
 
    /* Convert each of the strings into wide-character format. */ 
 
 
    if (mbstowcs(w_string1, "<a`>bcd", BUFF_SIZE) == (size_t)-1) { 
 
        perror("mbstowcs"); 
        exit(EXIT_FAILURE); 
    } 
 
 
    if (mbstowcs(w_string2, "abcz", BUFF_SIZE) == (size_t)-1) { 
 
        perror("mbstowcs"); 
        exit(EXIT_FAILURE); 
    } 
 
    /* Collate string 1 and string 2 and store the result. */ 
 
    errno = 0; 
    coll_result = wcscoll(w_string1, w_string2); 
    if (errno) { 
        perror("wcscoll"); 
        exit(EXIT_FAILURE); 
    } 
    else { 
 
       /*  Transform the strings (using wcsxfrm) into  */ 
       /*  w_string3 and w_string4.                    */ 
 
       wcsxfrm_result1 = wcsxfrm(w_string3, w_string1, BUFF_SIZE); 
 
       if (wcsxfrm_result1 == ((size_t) - 1)) 
           perror("wcsxfrm"); 
       else if (wcsxfrm_result1 > BUFF_SIZE) { 
           perror("\n** String is too long **\n"); 
           exit(EXIT_FAILURE); 
       } 
       else { 
          wcsxfrm_result2 = wcsxfrm(w_string4, w_string2, BUFF_SIZE); 
          if (wcsxfrm_result2 == ((size_t) - 1)) { 
              perror("wcsxfrm"); 
              exit(EXIT_FAILURE); 
           } 
          else if (wcsxfrm_result2 > BUFF_SIZE) { 
              perror("\n** String is too long **\n"); 
              exit(EXIT_FAILURE); 
           } 
 
        /* Compare the two transformed strings and verify that  */ 
        /* the result is the same as the result from wcscoll on */ 
        /* the original strings.                                */ 
 
          else { 
              wcscmp_result = wcscmp(w_string3, w_string4); 
              if (wcscmp_result == 0 && (coll_result == 0)) { 
                  printf("\nReturn value from wcscoll() and return value" 
                                       " from wcscmp() are both zero."); 
                  printf("\nThe program was successful\n\n"); 
              } 
              else if ((wcscmp_result < 0) && (coll_result < 0)) { 
                  printf("\nReturn value from wcscoll() and return value" 
                                  " from wcscmp() are less than zero."); 
                  printf("\nThe program was successful\n\n"); 
              } 
              else if ((wcscmp_result > 0) && (coll_result > 0)) { 
                  printf("\nReturn value from wcscoll() and return value" 
                                " from wcscmp() are greater than zero."); 
                  printf("\nThe program was successful\n\n"); 
              } 
              else { 
                  printf("** Error **\n"); 
                  printf("\nReturn values are not of the same type"); 
              } 
           } 
       } 
    } 
}

Running the example program produces the following result: 


Return value from wcscoll() and return value 
       from wcscmp() are less than zero. 
The program was successful

Previous Next Contents Index