Manual Pages for UNIX Operating System command usage for man wcstod

Standard C Library Functions                           wcstod(3C)



NAME
     wcstod, wcstof, wcstold, wstod, watof - convert wide charac-
     ter string to floating-point number

SYNOPSIS
     #include 

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


     float wcstof(const wchar_t *restrict nptr,
          wchar_t **restrict endptr);


     long double wcstold(const wchar_t *restrict nptr,
          wchar_t **restrict endptr);


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


     double watof(wchar_t *nptr);


DESCRIPTION
     The wcstod(), wcstof(), and wcstold() functions convert  the
     initial  portion  of the wide-character string pointed to by
     nptr to  double,  float,  and  long  double  representation,
     respectively.  They first decompose the input wide-character
     string into three parts:

         1.   An initial, possibly empty, sequence of white-space
              wide-character codes (as specified by iswspace(3C))

         2.   A subject sequence interpreted as a  floating-point
              constant or representing infinity or NaN

         3.   A  final  wide-character  string  of  one  or  more
              unrecognized  wide-character  codes,  including the
              terminating null wide-character code of  the  input
              wide-character string.


     Then they attempt to  convert  the  subject  sequence  to  a
     floating-point number, and return the result.


     The expected form of the subject  sequence  is  an  optional
     plus or minus sign, then one of the following:

         o    A non-empty sequence of decimal  digits  optionally



SunOS 5.11          Last change: 31 Mar 2003                    1






Standard C Library Functions                           wcstod(3C)



              containing  a  radix  character,  then  an optional
              exponent part

         o    A 0x or 0X, then a non-empty  sequence  of  hexade-
              cimal  digits optionally containing a radix charac-
              ter, then an optional binary exponent part

         o    One of INF or INFINITY, or any  other  wide  string
              equivalent except for case

         o    One of NAN or  NAN(n-wchar-sequence(opt)),  or  any
              other  wide  string  ignoring case in the NAN part,
              where:

                n-wchar-sequence:
                    digit
                    nondigit
                    n-wchar-sequence digit
                    n-wchar-sequence nondigit



     In default mode for wcstod(),  only  decimal,  INF/INFINITY,
     and   NAN/NAN(n-char-sequence)   forms  are  recognized.  In
     C99/SUSv3 mode, hexadecimal strings are also recognized.


     In default mode for wcstod(),  the  n-char-sequence  in  the
     NAN(n-char-equence)  form  can  contain any character except
     ')' (right parenthesis) or '\0' (null).  In C99/SUSv3  mode,
     the  n-char-sequence  can  contain only upper and lower case
     letters, digits, and '_' (underscore).


     The wcstof() and  wcstold()  functions  always  function  in
     C99/SUSv3-conformant mode.


     The subject sequence  is  defined  as  the  longest  initial
     subsequence  of  the  input  wide  string, starting with the
     first  non-white-space  wide  character,  that  is  of   the
     expected form. The subject sequence contains no wide charac-
     ters if the input wide string is not of the expected form.


     If  the  subject  sequence  has  the  expected  form  for  a
     floating-point  number,  the  sequence  of  wide  characters
     starting with the first digit or the radix character (which-
     ever  occurs  first)  is  interpreted as a floating constant
     according to the rules of the C language,  except  that  the
     radix  character  is  used in place of a period, and that if
     neither an exponent part nor a radix character appears in  a



SunOS 5.11          Last change: 31 Mar 2003                    2






Standard C Library Functions                           wcstod(3C)



     decimal  floating-point number, or if a binary exponent part
     does not appear in a hexadecimal floating-point  number,  an
     exponent  part  of  the  appropriate type with value zero is
     assumed to follow the last digit in the string. If the  sub-
     ject  sequence  begins  with  a  minus sign, the sequence is
     interpreted as negated. A  wide-character  sequence  INF  or
     INFINITY  is  interpreted  as  an infinity. A wide-character
     sequence NAN or NAN(n-wchar-sequence(opt)) is interpreted as
     a quiet NaN. A pointer to the final wide string is stored in
     the object pointed to by endptr, provided that endptr is not
     a null pointer.


     If the subject sequence has either the  decimal  or  hexade-
     cimal  form,  the  value  resulting  from  the conversion is
     rounded correctly according to the prevailing floating point
     rounding direction mode. The conversion also raises floating
     point  inexact,  underflow,  or   overflow   exceptions   as
     appropriate.


     The radix character  is  defined  in  the  program's  locale
     (category  LC_NUMERIC).  In the POSIX locale, or in a locale
     where the radix character is not defined, the radix  charac-
     ter defaults to a period ('.').


     If the subject sequence  is  empty  or  does  not  have  the
     expected  form,  no  conversion  is  performed; the value of
     nptr is stored in the object pointed to by endptr,  provided
     that  endptr is not a null pointer.


     The wcstod() function does not change the setting  of  errno
     if successful.


     The wstod() function is identical to wcstod().


     The  watof(str)  function  is  equivalent   to   wstod(nptr,
     (wchar_t **)NULL).

RETURN VALUES
     Upon successful completion, these functions return the  con-
     verted  value.  If  no  conversion  could be performed, 0 is
     returned.


     If the correct value is outside the range  of  representable
     values,  +_HUGE_VAL,  +_HUGE_VALF,  or  +_HUGE_VALL is returned
     (according to the sign  of  the  value),  a  floating  point



SunOS 5.11          Last change: 31 Mar 2003                    3






Standard C Library Functions                           wcstod(3C)



     overflow exception is raised, and errno is set to ERANGE.


     If the correct value would cause an underflow, the correctly
     rounded  result (which may be normal, subnormal, or zero) is
     returned, a floating point underflow  exception  is  raised,
     and errno is set to ERANGE.

ERRORS
     The wcstod() and wstod() functions will fail if:

     ERANGE    The value to be returned would cause  overflow  or
               underflow.



     The wcstod() and wcstod() functions may fail if:

     EINVAL    No conversion could be performed.


USAGE
     Because 0 is returned on error and is also a valid return on
     success,  an  application  wishing to check for error situa-
     tions  should  set  errno  to  0  call  wcstod(),  wcstof(),
     wcstold(),  or  wstod(), then check  errno and if it is non-
     zero, assume an error has occurred.

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     ____________________________________________________________
   |  ATTRIBUTE TYPE             |  ATTRIBUTE VALUE            |
   | ____________________________|_____________________________|_
   |  Interface Stability        |  wcstod(),   wcstof(),   and|
   |                             |  wcstold() are Standard.    |
   |_____________________________|_____________________________|
   | MT-Level                    | MT-Safe                     |
   |_____________________________|_____________________________|


SEE ALSO
     iswspace(3C),  localeconv(3C),   scanf(3C),   setlocale(3C),
     wcstol(3C), attributes(5), standards(5)








SunOS 5.11          Last change: 31 Mar 2003                    4