Initial revision

1 files changed, 464 insertions, 0 deletions

diff --git a/manual/arith.texi b/manual/arith.texi
new file mode 100644
index 0000000000..a0527f05e5
--- /dev/null
+++ b/manual/arith.texi
@@ -0,0 +1,464 @@
+@node Arithmetic
+@chapter Low-Level Arithmetic Functions
+
+This chapter contains information about functions for doing basic
+arithmetic operations, such as splitting a float into its integer and
+fractional parts.  These functions are declared in the header file
+@file{math.h}.
+
+@menu
+* Normalization Functions::		Hacks for radix-2 representations.
+* Rounding and Remainder Functions::	Determinining the integer and
+					 fractional parts of a float.
+* Integer Division::			Functions for performing integer
+					 division.
+* Parsing of Numbers::			Functions for ``reading'' numbers
+					 from strings.
+* Predicates on Floats::		Some miscellaneous test functions.
+@end menu
+
+@node Normalization Functions
+@section Normalization Functions
+@cindex normalization functions (floating-point)
+
+The functions described in this section are primarily provided as a way
+to efficiently perform certain low-level manipulations on floating point
+numbers that are represented internally using a binary radix;
+see @ref{Floating-Point Representation}.  These functions are required to
+have equivalent behavior even if the representation does not use a radix
+of 2, but of course they are unlikely to be particularly efficient in
+those cases.
+
+@comment math.h
+@comment GNU
+@deftypefun double copysign (double @var{value}, double @var{sign})
+The @code{copysign} function returns a value whose absolute value is the
+same as that of @var{value}, and whose sign matches that of @var{sign}.
+@end deftypefun
+
+@comment math.h
+@comment ANSI
+@deftypefun double frexp (double @var{value}, int *@var{exponent})
+The @code{frexp} function is used to normalize the number @var{value}.
+
+If the argument @var{value} is not zero, the return value is a
+floating-point number with magnitude in the range 1/2 (inclusive) to 1
+(exclusive).  The corresponding exponent is stored in the location
+pointed at by @var{exponent}; the return value multiplied by 2 raised to
+this exponent would equal the original number @var{value}.
+
+If @var{value} is zero, then both parts of the result are zero.
+@end deftypefun
+
+@comment math.h
+@comment ANSI
+@deftypefun double ldexp (double @var{value}, int @var{exponent})
+This function returns the result of multiplying the floating-point
+number @var{value} by 2 raised to the power @var{exponent}.  (It can
+be used to reassemble floating-point numbers that were taken apart
+by @code{frexp}.)
+@end deftypefun
+
+@c ??? Where does this come from?
+@comment math.h
+@comment GNU
+@deftypefun double scalb (double @var{value}, int @var{exponent})
+The @code{scalb} function does the same thing as @code{ldexp}.
+@end deftypefun
+
+@c ??? Where does this come from?
+@comment math.h
+@comment GNU
+@deftypefun double logb (double @var{x})
+This function returns the integer part of the base-2 logarithm of
+@var{x}, an integer value represented in type @code{double}.  This is
+the highest integer power of @code{2} contained in @var{x}.
+
+When @code{2} raised to this power is divided into @var{x}, it gives a
+quotient between @code{1} (inclusive) and @code{2} (exclusive).
+
+@strong{Incomplete:}  What happens if @var{x} is zero?
+@end deftypefun
+
+
+@node Rounding and Remainder Functions
+@section Rounding and Remainder Functions
+@cindex rounding functions
+@cindex remainder functions
+@cindex converting floats to integers
+
+The functions listed here perform operations such as rounding,
+truncation, and remainder in division of floating point numbers.  Some
+of these functions convert floating point numbers to integer values.
+
+You can also convert floating-point numbers to integers simply by
+casting them to @code{int}.  This discards the fractional part,
+effectively rounding towards zero.  However, this only works if the
+result can actually be represented as an @code{int}---for very large
+numbers, this is impossible.  The functions listed here return the
+result as a @code{double} instead to get around this problem.
+
+@comment math.h
+@comment ANSI
+@deftypefun double ceil (double @var{x})
+The @code{ceil} function rounds @var{x} upwards to the nearest integer,
+returning that value as a @code{double}.
+@end deftypefun
+
+@comment math.h
+@comment ANSI
+@deftypefun double floor (double @var{x})
+The @code{ceil} function rounds @var{x} downwards to the nearest
+integer, returning that value as a @code{double}.
+@end deftypefun
+
+@comment math.h
+@comment GNU
+@deftypefun double rint (double @var{x})
+This function returns the integer nearest @var{x} according to the
+current rounding mode.  @xref{Floating-Point Parameters}, for information
+about the @code{FLT_ROUNDS} macro.
+@end deftypefun
+
+@comment math.h
+@comment ANSI
+@deftypefun double modf (double @var{value}, double *@var{integer_part})
+This function breaks the argument @var{value} into an integer part and a
+fractional part (between @code{-1} and @code{1}, exclusive).  The
+integer part is stored at the location pointed at by @var{integer_part},
+and the fractional part is returned.  Their sum equals @var{value}.
+Each of the parts has the same sign as @var{value}, so the rounding of
+the integer part is towards zero.
+@end deftypefun
+
+
+@comment math.h
+@comment ANSI
+@deftypefun double fmod (double @var{numerator}, double @var{denominator})
+This function computes the remainder of dividing @var{numerator} by
+@var{denominator}.  Specifically, the return value is
+@code{@var{numerator} - @var{n} * @var{denominator}}, where @var{n} is
+the quotient of @var{numerator} by @var{denominator}, rounded down to
+the next lower integer.
+
+The result has the same sign as the @var{numerator} and has magnitude
+less than the magnitude of the @var{denominator}.  (Recall that the
+built-in @samp{%} operator isn't defined on floating-point values.)
+
+The following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item EDOM
+The @var{denominator} is zero.
+@end table
+@end deftypefun
+
+@comment math.h
+@comment GNU
+@deftypefun double drem (double @var{numerator}, double @var{denominator})
+This function returns the remainder from dividing @var{numerator} by
+@var{denominator}.  Specifically, the return value is @code{@var{numerator}
+- @var{n} * @var{denominator}}, where @var{n} is the integer closest to
+the exact quotient of @var{numerator} and @var{denominator}.  The absolute
+value of the result is less than or equal to one half the absolute value
+of the @var{denominator}.
+
+The following @code{errno} error conditions are defined for this function:
+
+@table @code
+@item EDOM
+The @var{denominator} is zero.
+@end table
+@end deftypefun
+
+
+@node Integer Division
+@section Integer Division
+@cindex integer division functions
+
+This section describes functions for performing integer division.  These
+functions are redundant in the GNU C library, since in GNU C the @samp{/}
+operator always rounds towards zero.  But in other C implementations,
+@samp{/} may round differently with negative arguments.  @code{div} and
+@code{ldiv} are useful because they specify how to round the quotient.
+
+These functions are specified to return a result @var{r} such that
+@code{@var{r}.quot*@var{denominator} + @var{r}.rem} equals
+@var{numerator}.
+
+To use these facilities, you should include the header file
+@file{stdlib.h} in your program.
+@pindex stdlib.h
+
+@comment stdlib.h
+@comment ANSI
+@deftp {Data Type} div_t
+This is a structure type used to hold the result returned by the @code{div}
+function.  It has the following members:
+
+@table @code
+@item int quot
+The quotient from the division.
+
+@item int rem
+The remainder from the division.
+@end table
+@end deftp
+
+@comment stdlib.h
+@comment ANSI
+@deftypefun div_t div (int @var{numerator}, int @var{denominator})
+This function @code{div} computes the quotient and remainder from
+the division of @var{numerator} by @var{denominator}, returning the
+result in a structure of type @code{div_t}.
+
+If the result cannot be represented (as in a division by zero), the
+behavior is undefined.
+@end deftypefun
+
+
+@comment stdlib.h
+@comment ANSI
+@deftp {Data Type} ldiv_t
+This is a structure type used to hold the result returned by the @code{ldiv}
+function.  It has the following members:
+
+@table @code
+@item long int quot
+The quotient from the division.
+
+@item long int rem
+The remainder from the division.
+@end table
+
+(This is identical to the type @code{div_t} except that the components
+are of type @code{long int} rather than @code{int}.)
+@end deftp
+
+@comment stdlib.h
+@comment ANSI
+@deftypefun ldiv_t ldiv (long int @var{numerator}, long int @var{denominator})
+The @code{ldiv} function is similar to @code{div}, except that the
+arguments are of type @code{long int} and the result is returned as a
+structure of type @code{ldiv}.
+@end deftypefun
+
+
+@node Parsing of Numbers
+@section Parsing of Numbers
+@cindex parsing numbers (in formatted input)
+@cindex converting strings to numbers
+@cindex number syntax, parsing
+@cindex syntax, for reading numbers
+
+This section describes functions for ``reading'' integer and
+floating-point numbers from a string.  In many cases, it is more
+appropriate to use @code{sscanf} or one of the related functions;
+see @ref{Formatted Input}.  The syntax recognized by the formatted input
+functions for the numeric conversions is exactly the same as the syntax
+recognized by the functions described in this section.
+
+These functions are declared in @file{stdlib.h}.
+@pindex stdlib.h
+
+@menu
+* Parsing of Integers::		Functions for conversion of integer values.
+* Parsing of Floats::		Functions for conversion of floating-point
+				 values.
+@end menu
+
+@node Parsing of Integers
+@subsection Parsing of Integers
+
+@comment stdlib.h
+@comment ANSI
+@deftypefun {long int} strtol (const char *@var{string}, char **@var{tailptr}, int @var{base})
+The @code{strtol} (``string-to-long'') function converts the initial
+part of @var{string} to a signed integer, which is returned as a value
+of type @code{long int}.  
+
+This function attempts to decompose @var{string} as follows:
+
+@itemize @bullet
+@item 
+A (possibly empty) sequence of whitespace characters.  Which characters
+are whitespace is determined by the @code{isspace} function
+(@pxref{Classification of Characters}).  These are discarded.
+
+@item 
+An optional plus or minus sign (@samp{+} or @samp{-}).
+
+@item 
+A nonempty sequence of digits in the radix specified by @var{base}.  If
+@var{base} is zero, decimal radix is assumed unless the series of digits
+begins with @samp{0} (specifying octal radix), or @samp{0x} or @samp{0X}
+(specifying hexadecimal radix); in other words, the same syntax that is
+used for integer constants in the C language is recognized.  Otherwise
+@var{base} must have a value between @code{2} and @code{35}.  If
+@var{base} is @code{16}, the digits may optionally be preceeded by
+@samp{0x} or @samp{0X}.
+
+@item 
+Any remaining characters in the string.  If @var{tailptr} is not a null
+pointer, a pointer to this tail of the string is stored in
+@code{*@var{tailptr}}.
+@end itemize
+
+If the string is empty, contains only whitespace, or does not contain an
+initial substring that has the expected syntax for an integer in the
+specified @var{base}, no conversion is performed.  In this case,
+@code{strtol} returns a value of zero and the value returned in
+@code{*@var{tailptr}} is the value of @var{string}.
+
+In a locale other than the standard @code{"C"} locale, this function
+may recognize additional implementation-dependent syntax.
+
+If the string has valid syntax for an integer but the value is not
+representable because of overflow, @code{strtol} returns either
+@code{LONG_MAX} or @code{LONG_MIN} (@pxref{Integer Representation
+Limits}), as appropriate for the sign of the value.
+
+The following @code{errno} error conditions are defined for this
+function:
+
+@table @code
+@item ERANGE
+An overflow condition was detected.
+@end table
+@end deftypefun
+
+@comment stdlib.h
+@comment ANSI
+@deftypefun {unsigned long int} strtoul (const char *@var{string}, char **@var{tailptr}, int @var{base})
+The @code{strtoul} (``string-to-unsigned-long'') function is similar to
+@code{strtol} except that it returns its value as an object of type
+@code{unsigned long int}.  The value returned in case of overflow is
+@code{ULONG_MAX} (@pxref{Integer Representation Limits}).
+@end deftypefun
+
+@comment stdlib.h
+@comment ANSI
+@deftypefun {long int} atol (const char *@var{string})
+This function is similar to the @code{strtol} function with a @var{base}
+argument of @code{10}, except that it need not detect overflow errors.
+The @code{atol} function is provided mostly for compatibility with
+existing code; using @code{strtol} is more robust.
+@end deftypefun
+
+@comment stdlib.h
+@comment ANSI
+@deftypefun int atoi (const char *@var{string})
+This function is similar to the @code{atol} function, except that
+returns its value as an @code{int} rather than @code{long int}.  The
+@code{atoi} function is also considered obsolete; use @code{strtol}
+instead.
+@end deftypefun
+
+
+@node Parsing of Floats
+@subsection Parsing of Floats
+
+@comment stdlib.h
+@comment ANSI
+@deftypefun double strtod (const char *@var{string}, char **@var{tailptr})
+The @code{strtod} (``string-to-double'') function converts the initial
+part of @var{string} to a floating-point number, which is returned as a
+value of type @code{double}.  
+
+This function attempts to decompose @var{string} as follows:
+
+@itemize @bullet
+@item 
+A (possibly empty) sequence of whitespace characters.  Which characters
+are whitespace is determined by the @code{isspace} function
+(@pxref{Classification of Characters}).  These are discarded.
+
+@item
+An optional plus or minus sign (@samp{+} or @samp{-}).
+
+@item
+A nonempty sequence of digits optionally containing a decimal-point
+character (@samp{.}).
+
+@item
+An optional exponent part, consisting of a character @samp{e} or
+@samp{E}, an optional sign, and a sequence of digits.
+
+@item
+Any remaining characters in the string.  If @var{tailptr} is not a null
+pointer, a pointer to this tail of the string is stored in
+@code{*@var{tailptr}}.
+@end itemize
+
+If the string is empty, contains only whitespace, or does not contain an
+initial substring that has the expected syntax for a floating-point
+number, no conversion is performed.  In this case, @code{strtod} returns
+a value of zero and the value returned in @code{*@var{tailptr}} is the
+value of @var{string}.
+
+In a locale other than the standard @code{"C"} locale, this function may
+recognize additional locale-dependent syntax.
+
+If the string has valid syntax for a floating-point number but the value
+is not representable because of overflow, @code{strtod} returns either
+positive or negative @code{HUGE_VAL} (@pxref{Mathematics}), depending on
+the sign of the value.  Similarly, if the value is not representable
+because of underflow, @code{strtod} returns zero.
+
+The following @code{errno} error conditions are defined for this
+function:
+
+@table @code
+@item ERANGE
+An overflow or underflow condition was detected.
+@end table
+@end deftypefun
+
+@comment stdlib.h
+@comment ANSI
+@deftypefun double atof (const char *@var{string})
+This function is similar to the @code{strtod} function, except that it
+need not detect overflow and underflow errors.  The @code{atof} function
+is provided mostly for compatibility with existing code; using
+@code{strtod} is more robust.
+@end deftypefun
+
+@node Predicates on Floats
+@section Predicates on Floats
+@cindex predicates on floats
+
+This section describes some miscellaneous test functions on doubles.
+Prototypes for these functions appear in @file{math.h}.
+@pindex math.h
+
+@comment math.h
+@comment GNU
+@deftypefun int isinf (double @var{x})
+This function returns @code{-1} if @var{x} represents negative infinity,
+@code{1} if @var{x} represents positive infinity, and @code{0} otherwise.
+@end deftypefun
+
+@comment math.h
+@comment GNU
+@deftypefun int isnan (double @var{x})
+This function returns a nonzero value if @var{x} is a ``not a number''
+value, and zero otherwise.
+@end deftypefun
+
+@comment math.h
+@comment GNU
+@deftypefun int finite (double @var{x})
+This function returns a nonzero value if @var{x} is finite or a ``not a
+number'' value, and zero otherwise.
+@end deftypefun
+
+@comment math.h
+@comment GNU
+@deftypefun double infnan (int @var{error})
+@strong{Incomplete:}  I don't understand what this function does.
+@end deftypefun
+
+@strong{Portability Note:} The functions listed in this section are GNU
+extensions.
+
+