[Cfp-interest] format - subgroup teleconference #3

Sat Jan 30 13:26:09 PST 2010

On Thu, 28 Jan 2010 16:26:58 -0800, Jim Thomas wrote:

>Also welcome early in the week would be a proposal 
>for functions to handle conversions between floating types and character 
>sequences. Any takers?

For both proposals:

Where TYPE and FP_TYPE come from:
      bN       _BinaryN
      dN       _DecimalN
      bNx      _BinaryNx
      dNx      _DecimalNx
[the above depends what naming convention we end up with]

================================================================

The following is based upon ISO/IEC TR 24731-1:2007(E) [WG14/N1225.pdf]
6.5.3.6 The sprintf_s function

6.x The strfromTYPE functions

Synopsis

1 #include <stdio.h>
  int strfromTYPE(char * restrict s, rsize_t n,
  const char * restrict format, FP_TYPE fp);

Runtime-constraints

2 Neither s nor format shall be a null pointer.  n shall neither equal
  zero nor be greater than RSIZE_MAX.  The number of characters
  (including the trailing null) required for the result to be written
  to the array pointed to by s shall not be greater than n.  The %n
  specifier 17) (modified or not by flags, field width, or precision)
  shall not appear in the string pointed to by format.  Any argument
  to strfromTYPE corresponding to a %s specifier shall not be a null
  pointer.  No encoding error shall occur.

3 If there is a runtime-constraint violation, then if s is not a null
  pointer and n is greater than zero and less than RSIZE_MAX, then the
  strfromTYPE function sets s[0] to the null character.

Description

4 The strfromTYPE function is "equivalent" to the sprintf function
  except for the parameter n, the explicit runtime-constraints listed
  above, only one argument is converted (no varargs), the length
  modifier is ignored in the format string, and references to "double
  argument" are replaced with "FP_TYPE argument".

5 The strfromTYPE function treats a result too big for the array
  pointed to by s as a runtime-constraint violation.

Returns

6 If no runtime-constraint violation occurred, the strfromTYPE
  function returns the number of characters written in the array, not
  counting the terminating null character.  If an encoding error
  occurred, strfromTYPE returns a negative value.  If any other
  runtime-constraint violation occurred, strfromTYPE returns zero.

17) It is not a runtime-constraint violation for the characters %n to
    appear in sequence in the string pointed at by format when those
    characters are not a interpreted as a %n specifier.  For example,
    if the entire format string was %%n.

================================================================

The following is based upon C1x [WG14/N1425]
7.21.1.3 The strtod, strtof, and strtold functions

7.x The strtoTYPE functions

Synopsis

1 #include <stdlib.h>
  FP_TYPE strtoTYPE(const char * restrict nptr,
                    char ** restrict endptr);

Description

2 The strtoTYPE functions convert the initial portion of the string
  pointed to by nptr to FP_TYPE representation. First, they decompose
  the input string into three parts: an initial, possibly empty,
  sequence of white-space characters (as specified by the isspace
  function), a subject sequence resembling a floating-point constant
  or representing an infinity or NaN; and a final string of one or
  more unrecognized characters, including the terminating null
  character of the input string. Then, they attempt to convert the
  subject sequence to a floating-point number, and return the result.

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

  -- a nonempty sequence of decimal digits optionally containing a
     decimal-point character, then an optional exponent part as
     defined in 6.4.4.2;

  -- a 0x or 0X, then a nonempty sequence of hexadecimal digits
     optionally containing a decimal-point character, then an optional
     binary exponent part as defined in 6.4.4.2;

  -- INF or INFINITY, ignoring case

  -- NAN or NAN(n-char-sequence opt), ignoring case in the NAN part,
     where:
       n-char-sequence:
         digit
         nondigit
         n-char-sequence digit
         n-char-sequence nondigit

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

4 If the subject sequence has the expected form for a floating-point
  number, the sequence of characters starting with the first digit or
  the decimal-point character (whichever occurs first) is interpreted
  as a floating constant according to the rules of 6.4.4.2, except
  that the decimal-point character is used in place of a period, and
  that if neither an exponent part nor a decimal-point character
  appears in a 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 subject sequence begins
  with a minus sign, the sequence is interpreted as negated.274) A
  character sequence INF or INFINITY is interpreted as an infinity, if
  representable in the return type, else like a floating constant that
  is too large for the range of the return type. A character sequence
  NAN or NAN(n-char-sequence opt), is interpreted as a quiet NaN, if
  supported in the return type, else like a subject sequence part that
  does not have the expected form; the meaning of the n-char sequences
  is implementation-defined.275) A pointer to the final string is
  stored in the object pointed to by endptr, provided that endptr is
  not a null pointer.

5 If the subject sequence has the hexadecimal form and FLT_RADIX is a
  power of 2, the value resulting from the conversion is correctly
  rounded.

6 In other than the "C" locale, additional locale-specific subject
  sequence forms may be accepted.

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

Recommended practice

8 If the subject sequence has the hexadecimal form, FLT_RADIX is not a
  power of 2, and the result is not exactly representable, the result
  should be one of the two numbers in the appropriate internal format
  that are adjacent to the hexadecimal floating source value, with the
  extra stipulation that the error should have a correct sign for the
  current rounding direction.

9 If the subject sequence has the decimal form and at most DECIMAL_DIG
  (defined in <float.h>) significant digits, the result should be
  correctly rounded. If the subject sequence D has the decimal form
  and more than DECIMAL_DIG significant digits, consider the two
  bounding, adjacent decimal strings L and U, both having DECIMAL_DIG
  significant digits, such that the values of L, D, and U satisfy L <=
  D <= U.  The result should be one of the (equal or adjacent) values
  that would be obtained by correctly rounding L and U according to
  the current rounding direction, with the extra

274) Negation happens before rounding.

275) An implementation may use the n-char sequence to determine extra
information to be represented in the NaNÆs significand.

---
Fred J. Tydeman        Tydeman Consulting
tydeman at tybor.com      Testing, numerics, programming
+1 (775) 358-9748      Vice-chair of PL22.11 (ANSI "C")
Sample C99+FPCE tests: http://www.tybor.com
Savers sleep well, investors eat well, spenders work forever.