Technical Reference: Base Operating System and Extensions, Volume 1

ecvt, fcvt, or gcvt Subroutine

Purpose

Converts a floating-point number to a string.

Library

Standard C Library (libc.a)

Syntax

#include <stdlib.h>

char *ecvt ( Value, NumberOfDigits, DecimalPointer, Sign;) double Value; int NumberOfDigits, *DecimalPointer, *Sign;

char *fcvt (Value, NumberOfDigits, DecimalPointer, Sign;)
double Value;
int  NumberOfDigits, *DecimalPointer, *Sign;

char *gcvt (Value, NumberOfDigits, Buffer;) double Value; int NumberOfDigits; char *Buffer;

Description

The ecvt, fcvt, and gcvt subroutines convert floating-point numbers to strings.

The ecvt subroutine converts the Value parameter to a null-terminated string and returns a pointer to it. The NumberOfDigits parameter specifies the number of digits in the string. The low-order digit is rounded according to the current rounding mode. The ecvt subroutine sets the integer pointed to by the DecimalPointer parameter to 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.) The decimal point itself is not included in the string. The ecvt subroutine also sets the integer pointed to by the Sign parameter to a nonzero value if the Value parameter is negative and sets a value of 0 otherwise.

The fcvt subroutine operates identically to the ecvt subroutine, except that the correct digit is rounded for C or FORTRAN F-format output of the number of digits specified by the NumberOfDigits parameter.

Note

In the F-format, the NumberOfDigits parameter is the number of digits desired after the decimal point. Large numbers produce a long string of digits before the decimal point, and then NumberOfDigits digits after the decimal point. Generally, the gcvt and ecvt subroutines are more useful for large numbers.

The gcvt subroutine converts the Value parameter to a null-terminated string, stores it in the array pointed to by the Buffer parameter, and then returns the Buffer parameter. The gcvt subroutine attempts to produce a string of the NumberOfDigits parameter significant digits in FORTRAN F-format. If this is not possible, the E-format is used. The gcvt subroutine suppresses trailing zeros. The string is ready for printing, complete with minus sign, decimal point, or exponent, as appropriate. The radix character is determined by the current locale (see setlocale subroutine). If the setlocale subroutine has not been called successfully, the default locale, POSIX, is used. The default locale specifies a . (period) as the radix character. The LC_NUMERIC category determines the value of the radix character within the current locale.

The ecvt, fcvt, and gcvt subroutines represent the following special values that are specified in ANSI/IEEE standards 754-1985 and 854-1987 for floating-point arithmetic:

Quiet NaN	Indicates a quiet not-a-number (NaNQ)
Signalling NaN	Indicates a signaling NaNS
Infinity	Indicates a INF value

The sign associated with each of these values is stored in the Sign parameter.

Note

A value of 0 can be positive or negative. In the IEEE floating-point, zeros also have signs and set the Sign parameter appropriately.

Attention: All three subroutines store the strings in a static area of memory whose contents are overwritten each time one of the subroutines is called.

Parameters

Value	Specifies some double-precision floating-point value.
NumberOfDigits	Specifies the number of digits in the string.
DecimalPointer	Specifies the position of the decimal point relative to the beginning of the string.
Sign	Specifies that the sign associated with the return value is placed in the Sign parameter. In IEEE floating-point, since 0 can be signed, the Sign parameter is set appropriately for signed 0.
Buffer	Specifies a character array for the string.

Related Information

The atof, strtod, atoff, or strtof (atof atoff Subroutine) subroutine, fp_read_rnd, or fp_swap_rnd (fp_read_rnd or fp_swap_rnd Subroutine) subroutine, printf (printf, fprintf, sprintf, snprintf, wsprintf, vprintf, vfprintf, vsprintf, or vwsprintf Subroutine) subroutine, scanf subroutine.

Subroutines Overview in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.