*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> wcstol (3)              
Title
Content
Arch
Section
 

wcstol(3)

Contents


NAME    [Toc]    [Back]

       wcstol - Convert a wide-character string to long integer

SYNOPSIS    [Toc]    [Back]

       #include <wchar.h>

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

LIBRARY    [Toc]    [Back]

       Standard C Library (libc)

STANDARDS    [Toc]    [Back]

       Interfaces  documented  on  this reference page conform to
       industry standards as follows:

       wcstol(): XSH5.0

       Refer to the standards(5) reference page for more information
 about industry standards and associated tags.

PARAMETERS    [Toc]    [Back]

       Contains a pointer to the wide-character string to be converted
 to a long  integer  representation.   Points  to  a
       pointer in which the wcstol() function stores the position
       in the string specified by the nptr parameter where a wide
       character  is  found that is not a valid character for the
       purpose of this conversion.  Specifies the radix in  which
       the characters are interpreted.

DESCRIPTION    [Toc]    [Back]

       The  wcstol() function converts the initial portion of the
       wide-character string pointed to by the nptr parameter  to
       a  long  integer  representation. The input wide-character
       string is  first  broken  down  into  three  parts:  White
       space--An  initial (possibly empty) sequence of wide-character
 spaces (as specified  by  the  iswspace()  function)
       Subject  sequence--A  sequence of wide characters that are
       valid in an integer constant of the  radix  determined  by
       the   base   parameter  Unrecognized  characters--A  final
       sequence of unrecognized wide-character  codes,  including
       the terminating null wide character

       If  possible,  the subject is then converted to an integer
       and the result is returned.

       The base parameter can take values between 0 and  36.   If
       the  base  value  is 0 (zero), the subject string can be a
       decimal, octal, or hexadecimal integer constant. A decimal
       constant  begins  with  a  nonzero digit and consists of a
       sequence of decimal digits. An octal constant consists  of
       the  prefix  0 (zero) optionally followed by a sequence of
       digits in the range 0 through 7.  A  hexadecimal  constant
       consists  of  the  prefix  0x or oX followed by a sequence
       consisting of decimal digits and the letters in the  range
       a  (or A) to f (or F).  If the base value is between 2 and
       36, the subject string can be a sequence of digits and the
       letters  a (or A) to z ( or Z ) that are used to represent
       an integer in the specified  base.  Alphabetic  characters
       represent  digits with an equivalent decimal value from 10
       (for the letter A) to 35 (for the letter Z).  The  subject
       string  can  have  only digits with a value less than base
       and alphabetic characters with equivalent values less than
       base. For example, when the value of the base parameter is
       20, only the following value assignments are converted:

              Character  0 1 2 3 4 5 6 7 8 9   A  B  C  D   E   F
              G  H  I  J
                                               a   b   c  d  e  f
              g  h  i  j Value  0 1 2 3 4 5 6 7 8 9 10 11  12  13
              14 15 16 17 18 19


       The subject string can optionally be preceded by a + (plus
       sign) or - (minus sign), but  cannot  include  an  integer
       suffix  (such as L).  If the subject string is preceded by
       a - (minus sign), the converted integer value has a  negative
  value. If the value of base is 16, the characters 0x
       or 0X may optionally precede the sequence  of  letters  or
       digits, following the sign, if present.

       The  wide-character  string  is parsed to skip the initial
       space characters (as  determined  by  theiswspace()  function).
  Any nonspace character is the start of a potential
       subject string that may form an integer in the base specified
  by  the  base  parameter.  The  subject  sequence is
       defined to be the longest initial substring that is of the
       expected form of long integer. Any character that does not
       satisfy this expected form begins the  final  sequence  of
       unrecognized  characters.  The  wcstol() function sets the
       *endptr parameter to  point  to  this  final  sequence  of
       unrecognized characters.

       If  the  subject  sequence  is  empty or does not have the
       expected form, the function  performs  no  conversion.  In
       this case, provided that endptr is not a null pointer, the
       function stores the value of nptr in the object pointed to
       by endptr.

       The  LC_CTYPE  category  of the locale controls which wide
       characters are treated as spaces but does not  affect  the
       interpretation  of  characters  as  part  of  the  subject
       string. The characters in the subject  string  are  always
       treated  as  if the locale was the POSIX (C) locale. (Current
 industry standards allow  conforming  implementations
       to support forms of subject sequences in addition to those
       in the POSIX (C) locale. On Tru64 UNIX systems, this additional
 support is unnecessary.)

RETURN VALUES    [Toc]    [Back]

       If  the wcstol() function finds the expected subject form,
       the converted value of long integer is returned. The function
  returns  0 (zero) if it does not convert the subject
       value. If the converted value is outside the range of representable
   values,  the  function  returns  LONG_MAX  or
       LONG_MIN (according to the sign of the subject value).

       If the endptr parameter is not a  null  pointer,  wcstol()
       stores  a  pointer  to  the final sequence of unrecognized
       characters in *endptr except when the subject sequence  is
       empty  or  invalid. In this case, wcstol() stores the nptr
       pointer in the *endptr parameter.

       Since 0 (zero), LONG_MIN, and LONG_MAX are returned in the
       event  of  an  error  and  are  also  valid returns if the
       wcstol() function is successful, applications  should  set
       errno  to  0 (zero) before each call to the wcstol() function,
 and check errno after each return from the  wcstol()
       function.  If  errno  is nonzero, an error occurred. Additionally,
 if 0 (zero)  is  returned,  applications  should
       check  if  the endptr parameter equals the nptr parameter.
       In this case, there was no valid subject string.

ERRORS    [Toc]    [Back]

       If any of the following  conditions  occur,  the  wcstol()
       function  sets  errno to the corresponding value: The base
       parameter has an unsupported value (less than 0 or greater
       than 36).

              [Tru64 UNIX]  The nptr parameter is a null pointer.
              The converted value is outside the range of  representable
 values.

EXAMPLES    [Toc]    [Back]

       The  following example converts a wide-character string to
       a signed long integer:

       #include <stdio.h> #include <wchar.h> #include  <locale.h>
       #include <errno.h> #define WLENGTH 40


       main {
           wchar_t WCString[WLENGTH], *endptr;
           long int    retval;


           (void)setlocale(LC_ALL, "");
           if (fgetws(WCString, WLENGTH, stdin) != NULL) {
               errno = 0;


               retval = wcstol ( WCString, &endptr, 0 );


               if (retval == 0 && (errno != 0
                                   || WCString == endptr)) {
                   /* No conversion could be performed */
                   printf("No conversion performed\n");
               } else if (errno != 0 && (retval == LONG_MAX
                                         ||  retval == LONG_MIN))
       {
                   /* Error handling */
               } else {
                   /* retval contains long integer */
                   printf("Integer in decimal is %d\n", retval);
               }
            } }

SEE ALSO    [Toc]    [Back]

      
      
       Functions:  atoi(3),  iswalnum(3),  scanf(3),   wcstod(3),
       wcstoul(3), wctype(3), wscanf(3)

       Standards: standards(5)



                                                        wcstol(3)
[ Back ]
 Similar pages
Name OS Title
wcstol IRIX convert wide character string to long integer, unsigned long integer, long long integer, unsigned long long in
wcstoull FreeBSD convert a wide character string value to a long, unsigned long, long long, unsigned long long, intma...
wcstol FreeBSD convert a wide character string value to a long, unsigned long, long long, unsigned long long, intma...
wcstoul FreeBSD convert a wide character string value to a long, unsigned long, long long, unsigned long long, intma...
wcstoll FreeBSD convert a wide character string value to a long, unsigned long, long long, unsigned long long, intma...
wcstoimax FreeBSD convert a wide character string value to a long, unsigned long, long long, unsigned long long, intma...
wcstoumax FreeBSD convert a wide character string value to a long, unsigned long, long long, unsigned long long, intma...
wcstoul Tru64 Convert wide-character strings to unsigned long integer
strtoq FreeBSD convert a string value to a long, long long, intmax_t or quad_t integer
strtoll NetBSD convert string value to a long, long long, intmax_t or quad_t integer
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service