Content-type: text/html Man page of ecvt

ecvt

Section: C Library Functions (3)
Index Return to Main Contents
 

NAME

ecvt, ecvt_r, fcvt, fcvt_r, gcvt - Convert a floating-point number to a string  

LIBRARY

Standard C Library (libc.a)  

SYNOPSIS

#include <stdlib.h>

char *ecvt(        double value,
       int num_digits,
       int *decimal_ptr,
       int *sign);

char *fcvt(        double value,
       int num_digits,
       int *decimal_ptr,
       int *sign);

char *gcvt(        double value,
       int num_digits,
       char *buffer);

The following obsolete functions are supported in order to maintain backward compatibility with previous versions of the operating system. You should not use them in new designs. int ecvt_r(        double value,
       int num_digits,
       int *decimal_ptr,
       int *sign,
       char *buffer,
       int len );

int fcvt_r(        double value,
       int num_digits,
       int *decimal_ptr,
       int *sign,
       char *buffer,
       int len );
 

PARAMETERS

Specifies the double value to be converted. Specifies the number of digits in the resulting string. Holds the position of the decimal point relative to the beginning of the string. A negative number means the decimal point is to the left of the digits given in the string. Holds a value of 0 (zero) if the value is positive or zero, and a nonzero value if it is negative. Specifies the character array to be used as scratch space in calculations and for storing the resulting string. Specifies the length of buffer. Because ecvt temporarily stores intermediate results of its calculations in the buffer, you must specify a len greater than 370. A value of 400 is recommended.  

DESCRIPTION

The ecvt(), fcvt(), and gcvt() functions convert floating-point numbers to null-terminated strings.

The ecvt() function converts the value specified by the value parameter to a null-terminated string of length num_digits, and returns a pointer to it. The resulting low-order digit is rounded according to the current rounding mode. The decimal_ptr parameter is assigned to the position of the decimal point relative to the position of the string. The sign parameter is assigned a value of 0 (zero) if value is positive or zero, and a nonzero value if value is negative. The decimal point and sign are not included in the string.

The fcvt() function is the same as the ecvt() function, except that it rounds to the correct digit for outputting num_digits of digits in C or FORTRAN F-format. In the F-format, num_digits is taken as the number of digits desired after the decimal point.

The gcvt() function converts the value specified by the value parameter to a null-terminated string, stores it in the array pointed to by the buffer parameter, and then returns buffer. The gcvt() function attempts to produce a string of num_digits significant digits in FORTRAN F-format. If this is not possible, then E-format is used. The string is ready for printing, complete with minus sign, decimal point, or exponent, as appropriate. Trailing zeros are suppressed.

In the F-format, num_digits is the number of digits desired after the decimal point. Very large numbers produce a very long string of digits before the decimal point, and then num_digits of digits after the decimal point. For large numbers, it is preferable to use the gcvt() or ecvt() function so that the E-format will be used.

The ecvt(), fcvt(), and gcvt() functions represent the following special values that are specified in IEEE Standard 754-1985 for floating-point arithmetic according to the following table.

ValueRepresentation

Quiet NaNNaNQ
Signalling NaNNaNS
+InfinityINF
-Infinity-INF

The sign associated with each of these values is stored into the sign parameter. Note, also, that in IEEE floating point operations, a value of 0 (zero) can be positive or negative, as set by the sign parameter.  

NOTES

The ecvt(), fcvt(), and gcvt() functions store the converted string in a thread-specific buffer. Subsequent calls to these functions from the same thread overwrite the contents of the internal buffer.

The ecvt_r() and fcvt_r() functions are obsolete reentrant versions of the ecvt() and fcvt() functions. They are supported in order to maintain backward compatibility with previous versions of the operating system and should not be used in new designs.  

RETURN VALUES

The ecvt(), fcvt(), and gcvt() functions return the converted string.

Upon successful completion, the ecvt_r() and fcvt_r() functions store the converted string in the array pointed to by the buffer parameter, and return a value of 0 (zero). Upon failure, these functions return -1 and may set errno.  

ERRORS

If the ecvt_r() or fcvt_r() function fails, errno may be set to the following value: The buffer parameter is invalid or too small.  

RELATED INFORMATION

Functions: atof(3), printf(3), scanf(3).

delim off


 

Index

NAME
LIBRARY
SYNOPSIS
PARAMETERS
DESCRIPTION
NOTES
RETURN VALUES
ERRORS
RELATED INFORMATION

This document was created by man2html, using the manual pages.
Time: 02:42:00 GMT, October 02, 2010