Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

12    math.h

Palm OS® Protein C/C++ Compiler Language & Library Reference

Palm OS® Developer Suite

The <math.h> header defines several mathematical functions.

This header is new with Palm OS® Protein. It is a broad subset of section 7.12 of the C language standard ANSI/ISO/IEC 9899:1999.

MathLib is part of SystemLib. To use MathLib, simply include the <math.h> header in your source files.

Supported features

The Palm OS Protein C/C++ Compiler supports the use of infinity and NaN (not-a-number) values.

The following C99 macros are supported in <math.h>:

  • FLT_EVAL
  • FP_ILOGBNAN
  • FP_ILOGB0
  • FP_INFINITE
  • FP_NAN
  • FP_NORMAL
  • FP_SUBNORMAL
  • FP_ZER0
  • HUGE_VAL
  • HUGE_VALF
  • HUGE_VALL
  • INFINITY
  • MATH_ERREXCEPT
  • math_errhandling
  • MATH_ERRNO
  • NAN

Differences from the C99 specification

  • All of <math.h> as specified in the C language standard ANSI/ISO/IEC 9899:1990 is provided as well as most of the extensions specified in 1999 standard. Parts of <math.h> that are not supported are listed under the line:

    #ifdef __USE_C99_EXTENSIONS__

    Functions in this section are preprocessed out by default and are not tested or supplied by PalmSource.

  • Parallel sets of functions for float and long double arguments types are defined only for 1989 ANSI C functions.

Constraints

  • Existing 68K applications must continue to supply the 68K MathLib if required by the application.
  • There are cases in which the behavior of the math library with respect to the errno error reporting mechanism are implementation defined. For details on how the Palm OS Protein C/C++ Compiler handles errors in these cases, see "Behavior of errno."
  • The float and long double overloads as specified in section 26.5 of the ANSI C++ standard are not provided.
  • The float and long double counterparts suffixed by "f" and "l" for the functions defined in section 7.12 of the 1989 ANSI C language standard are supported. A few of the float counterparts have Palm OS implementations, but most of these simply cast and return the double version.
  • A handful of single precision counterparts are provided as a high performance alternative to their double equivalents. However, there are some additional deviations from the standard that were made to achieve high performance, including:
    • none of the single precision functions set the global variable errno.
    • sqrtf() flushes denormals to zero (0).
    • ceilf(-0) is 0 not –0 as specified in Annex F.9.6.1 of the ANSI standard.
    • hypotf() does not follow the spec for NaNs and infinities.
  • The library, libm.a, is no longer supported and must be removed from existing projects.

Behavior of errno

There are two situations in which case an infinite result can occur as the result of an operation. The first is when a range error occurs, where the computation using finite arguments causes a result that lies outside the range of values that can be represented by the data type. The second case is when the result is infinite because the mathematics involved actually results in an infinite result (such as when an input argument is infinite). In this case, there is no range error, but the result is still infinite.

Some functions only have two ways to result in an infinite value—either the result is infinite, or the result cannot be represented due to its size. In this case, errno can be useful, because it will indicate no error if the result is in fact infinity, or ERANGE if a range error occurred.

On the other hand, if the function has multiple ways in which infinity can be the result, errno cannot be used as a method for determining whether or not the value is legitimate or not.

For this reason, the Palm OS Protein C/C++ Compiler handles errno in these cases as follows:

errno is set only when it can be used to definitively distinguish between multiple ways of arriving at the same return value. One should not expect errno to be set in cases where it will not help determine the reason why the result was achieved. See Table 12.1.

Table 12.1  errno handling for specific cases

Function Name

Sets errno

Explanation

hypot()

ERANGE

Overflow occurs when hypot(finite but large, finite) is called.

scalbn() / ldexp()

no

Too many ways for infinity to result

nextafter()

ERANGE

nextafter(DBL_MAX, INFINITY)

ilogb()

no

Both 0 and denormals have the exponent 0.

logb() / log10() / log()

EDOM

logx(0) isn't equal to logx(denormal).

pow()

ERANGE

pow(finite > 0, finite large > 0) indicates that overflow occurred. Required by section 7.12.1 of the standard.

pow(INFINITY, INFINITY)

no

Overflow does not occur, since the original values were not finite.

any function(NaN)

no

Ideally, the function should propagate the same NaN that was passed in, with no additional side effects

cos(x=±inf) / sin(x=±inf) / tan(x=–inf)

EDOM

Distinguishes between x being infinite or NaN. Also, the limit as x approaches infinity does not exist.