Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Next Page > Hide TOC

Mathematical and Logical Utilities Reference

Framework
CoreServices/CoreServices.h
Declared in
FixMath.h
MacTypes.h
Math64.h
ToolUtils.h
fenv.h
fp.h

Overview

Important:  This is a preliminary document. Although it has been reviewed for technical accuracy, it is not final. Apple Computer is supplying this information to help you plan for the adoption of the technologies and programming interfaces described herein. This information is subject to change, and software implemented according to this document should be tested with final operating system software and final documentation. For information about updates to this and other developer documentation, you can check the ADC Reference Library Revision List. To receive notification of documentation updates, you can sign up for ADC's free Online Program and receive the weekly Apple Developer Connection News email newsletter. (See http://developer.apple.com/membership for more details about the Online Program.)

You can use the Mathematical and Logical Utilities to perform mathematical and logical operations in Mac OS X programming. This document describes functions you can use to:

With the exception of the mathematical operations and conversions, these utilities are intended for programmers who occasionally need to access some of these features and do not require that the algorithms used to implement them be sophisticated. For example, if you are developing an advanced mathematical application, the pseudorandom number generator built into Mac OS might be too simplistic to fit your needs. Similarly, if you wish to access individual bits of memory in a time-critical loop, these routines are probably too slow to be practical.

Carbon supports the Mathematical and Logical Utilities, with the exception of those functions that are 68K-specific. However there are several important differences between the implementation of the Mathematical and Logical Utilities in Mac OS 9 and its implementation in Mac OS X.

The implementation in Carbon on Mac OS X of many floating-point functions defined in fp.h is not as accurate as the implementation of those functions in MathLib on Mac OS 8 and 9 (as accessed either directly or through CarbonLib). There are a number of reasons for this difference, including the different expectations of Mac OS 9 and UNIX floating-point clients, compiler limitations, and the need in for an implementation that’s independent of assumptions about the size and layout of floating-point data types.

Functions which take parameters or return values of type long double are not exported by the Core Services framework on Mac OS X. Instead, these functions have been replaced with macros that map to the corresponding double-typed functions. While these functions are exported by CarbonLib, CFM applications calling these functions on Mac OS X should note that the implementations of the long double functions on Mac OS X actually have only double precision, with the following four exceptions: num2decl, dec2numl, x80told, and ldtox80.

Functions by Task

Converting Among 32-Bit Numeric Types

Converting Between Fixed-Point and Floating-Point Values

Converting Between Fixed-Point and Integral Values

Getting and Setting Memory Values

Multiplying and Dividing Fixed-Point Numbers

Performing Calculations on Fixed-Point Numbers

Performing Logical Operations

Testing and Setting Bits

Miscellaneous Functions

Functions

acos

double_t acos (
   double_t x
);

Parameters
x
Return Value
Availability
Declared In
fp.h

acosh

double_t acosh (
   double_t x
);

Parameters
x
Return Value
Availability
Declared In
fp.h

annuity

double annuity (
   double rate,
   double periods
);

Parameters
rate
periods
Return Value
Availability
Declared In
fp.h

asin

double_t asin (
   double_t x
);

Parameters
x
Return Value
Availability
Declared In
fp.h

asinh

double_t asinh (
   double_t x
);

Parameters
x
Return Value
Availability
Declared In
fp.h

atan

double_t atan (
   double_t x
);

Parameters
x
Return Value
Availability
Declared In
fp.h

atan2

double_t atan2 (
   double_t y,
   double_t x
);

Parameters
y
x
Return Value
Availability
Declared In
fp.h

atanh

double_t atanh (
   double_t x
);

Parameters
x
Return Value
Availability
Declared In
fp.h

BitAnd

Performs the AND logical operation on two long words.

long BitAnd (
   long value1,
   long value2
);

Parameters
value1

A long word.

value2

A long word.

Return Value

A long word that is the result of the AND operation on the long words passed as arguments. Each bit in the returned value is set if and only if the corresponding bit is set in both value1 and value2.

Availability
Declared In
ToolUtils.h

BitClr

Clears a particular bit (to a value of 0).

void BitClr (
   void *bytePtr,
   long bitNum
);

Parameters
bytePtr

A pointer to a byte in memory.

bitNum

The bit to be cleared, specified as a positive offset from the high-order bit of the byte pointed to by the bytePtr parameter. The bit being cleared need not be in the same byte pointed to by bytePtr.

Special Considerations

The bit numbering scheme used by the BitClr function is the opposite of the MC680x0 numbering. To convert an MC680x0 bit number to the format required by the BitClr function, subtract the MC680x0 bit number from the highest bit number.

Availability
Declared In
ToolUtils.h

BitNot

Performs the NOT logical operation on a long word.

long BitNot (
   long value
);

Parameters
value

A long word.

Return Value

A long word that is the result of the NOT operation on the long word passed in as an argument. Each bit in the returned value is set if and only if the corresponding bit is not set in value.

Availability
Declared In
ToolUtils.h

BitOr

Performs the OR logical operation on two long words.

long BitOr (
   long value1,
   long value2
);

Parameters
value1

A long word.

value2

A long word.

Return Value

A long word that is the result of the OR operation on the long words passed as arguments. Each bit in the returned value is set if and only if the corresponding bit is set in value1 or value2, or in both value1 and value2.

Availability
Declared In
ToolUtils.h

BitSet

Sets a particular bit (to a value of 1).

void BitSet (
   void *bytePtr,
   long bitNum
);

Parameters
bytePtr

A pointer to a byte in memory.

bitNum

The bit to be set, specified as a positive offset from the high-order bit of the byte pointed to by the bytePtr parameter. The bit being set need not be in the byte pointed to by bytePtr.

Special Considerations

The bit numbering scheme used by the BitSet function is the opposite of the MC680x0 numbering. To convert an MC680x0 bit number to the format required by the BitSet function, subtract the MC680x0 bit number from the highest bit number.

Availability
Declared In
ToolUtils.h

BitShift

Shifts bits in a long word.

long BitShift (
   long value,
   short count
);

Parameters
value

A long word.

count

The number of bits to shift. If this number is positive, BitShift shifts this many positions to the left; if this number is negative, BitShift shifts this many positions to the right. The value in this parameter is converted to the result of MOD 32.

Return Value

A long word that is the result of shifting the bits in the long word passed in as an argument. The shift’s direction and extent are determined by the count parameter. Zeroes are shifted into empty positions regardless of the direction of the shift.

Availability
Declared In
ToolUtils.h

BitTst

Determines whether a given bit is set.

Boolean BitTst (
   const void *bytePtr,
   long bitNum
);

Parameters
bytePtr

A pointer to a byte in memory.

bitNum

The bit to be tested, specified as a positive offset from the high-order bit of the byte pointed to by the bytePtr parameter. The bit being tested need not be in the byte pointed to by bytePtr.

Return Value

TRUE if the specified bit is set (that is, has a value of 1) and FALSE if the bit is cleared (that is, has a value of 0).

Special Considerations

The bit numbering scheme used by the BitTst function is the opposite of the MC680x0 numbering. To convert an MC680x0 bit number to the format required by the BitTst function, subtract the MC680x0 bit number from the highest bit number.

Availability
Declared In
ToolUtils.h

BitXor

Performs the XOR logical operation on two long words.

long BitXor (
   long value1,
   long value2
);

Parameters
value1

A long word.

value2

A long word.

Return Value

A long word that is the result of the XOR operation on the long words passed in as arguments. Each bit in the returned value is set if and only if the corresponding bit is set in either value1 or value2, but not in both value1 and value2.

Availability
Declared In
ToolUtils.h

ceil

double_t ceil (
   double_t x
);

Parameters
x
Return Value
Availability
Declared In
fp.h

compound

double compound (
   double rate,
   double periods
);

Parameters
rate
periods
Return Value
Availability
Declared In
fp.h

copysign

double_t copysign (
   double_t x,
   double_t y
);

Parameters
x
y
Return Value
Availability
Declared In
fp.h

cos

double_t cos (
   double_t x
);

Parameters
x
Return Value
Availability
Declared In
fp.h

cosh

double_t cosh (
   double_t x
);

Parameters
x
Return Value
Availability
Declared In
fp.h

dec2f

float dec2f (
   const decimal *d
);

Parameters
d
Availability
Declared In
fp.h

dec2l

long dec2l (
   const decimal *d
);

Parameters
d
Availability
Declared In
fp.h

dec2num

double_t dec2num (
   const decimal *d
);

Parameters
d
Return Value
Availability
Declared In
fp.h

dec2s

short dec2s (
   const decimal *d
);

Parameters
d
Availability
Declared In
fp.h

dec2str

void dec2str (
   const decform *f,
   const decimal *d,
   char *s
);

Parameters
f
d
s
Availability
Declared In
fp.h

dtox80

void dtox80 (
   const double *x,
   extended80 *x80
);

Parameters
x
x80
Availability
Declared In
fp.h

erf

double_t erf (
   double_t x
);

Parameters
x
Return Value
Availability
Declared In
fp.h

erfc

double_t erfc (
   double_t x
);

Parameters
x
Return Value
Availability
Declared In
fp.h

exp

double_t exp (
   double_t x
);

Parameters
x
Return Value
Availability
Declared In
fp.h

exp2

double_t exp2 (
   double_t x
);

Parameters
x
Return Value
Availability
Declared In
fp.h

expm1

double_t expm1 (
   double_t x
);

Parameters
x
Return Value
Availability
Declared In
fp.h

fabs

double_t fabs (
   double_t x
);

Parameters
x
Return Value
Availability
Declared In
fp.h

fdim

double_t fdim (
   double_t x,
   double_t y
);

Parameters
x
y
Return Value
Availability
Declared In
fp.h

Fix2Frac

Converts a Fixed number to a Fract number.

Fract Fix2Frac (
   Fixed x
);

Parameters
x

The Fixed number to be converted to a Fract number.

Return Value

The Fract number equivalent to the Fixed number x. If x is greater than the maximum representable Fract number, the Fix2Frac function returns $7FFFFFFF. If x is less than the negative number with the highest absolute value, Fix2Frac returns $80000000.

Availability
Declared In
FixMath.h

Fix2Long

Converts a Fixed number to a LongInt number.

SInt32 Fix2Long (
   Fixed x
);

Parameters
x

The Fixed number to be converted to a long integer.

Return Value

The long integer nearest to the Fixed number x. If x is halfway between two integers (0.5), it is rounded to the integer with the higher absolute value.

Availability
Declared In
FixMath.h

Fix2X

Converts a Fixed number to an Extended number.

double Fix2X (
   Fixed x
);

Parameters
x

The Fixed number to be converted to an Extended number.

Return Value

The Extended equivalent of the Fixed number x.

Special Considerations

Fix2X does not move memory; you can call it at interrupt time.

Availability
Declared In
FixMath.h

FixATan2

Obtains a fast approximation of the arctangent of a fraction.

Fixed FixATan2 (
   SInt32 x,
   SInt32 y
);

Parameters
x

The numerator of the fraction whose arctangent is to be obtained. This variable can be a LongInt, Fixed, or Fract number.

y

The denominator of the fraction whose arctangent is to be obtained. The number supplied in this variable must be of the same type as that of the number supplied in the x parameter.

Return Value

The arctangent of y/x, in radians.

Discussion

The approximation of p/4 used to compute the arctangent is the hexadecimal value 0.C910, making the approximation of p equal to 3.1416015625, while p itself equals 3.14159265.... Thus FixATan2(1, 1) equals the equivalent of the hexadecimal value 0.C910. Despite the approximation of p, the arctangent value obtained will usually be correct to several decimal places.

Availability
Declared In
FixMath.h

FixDiv

Divides two variables of the same type (Fixed, Fract, or LongInt) or to divide a LongInt or Fract number by a Fixed number.

Fixed FixDiv (
   Fixed x,
   Fixed y
);

Parameters
x

The first operand, which can be a variable of type Fixed or a variable of type Fract or LongInt.

y

The second operand, which can be a variable of type Fixed or it can be a variable of the same type as the variable in parameter x.

Return Value

The quotient of the numbers in x and y. If the y parameter is in the format of a Fixed number, then the x parameter can be in the format of a Fixed, Fract, or LongInt number. If the y parameter is in the format of a Fract or LongInt number, then the x parameter must be in the same format.

The returned value is in the format of a Fixed number if both x and y are both Fixed numbers, both Fract numbers, or both LongInt numbers. Otherwise, the returned value is the same type as the number in the x parameter.

Division by zero results in $8000000 if x is negative, and $7FFFFFFF otherwise; thus the special case 0/0 yields $7FFFFFFF.

Availability
Declared In
FixMath.h

FixedToFloat

Converts a Fixed number to a float number. 

float FixedToFloat (
   Fixed x
);

Parameters
x

The Fixed number to be converted.

Return Value

The float equivalent of the Fixed number.

Discussion

This function is implemented as an inline macro.

Availability
Declared In
FixMath.h

FixMul

Multiplies a variable of type Fixed with another variable of type Fixed or with a variable of type Fract or LongInt.

Fixed FixMul (
   Fixed a,
   Fixed b
);

Parameters
a

The first operand, which can be a variable of type Fixed or a variable of type Fract or LongInt.

b

The second operand, which can be a variable of type Fixed or a variable of type Fract or LongInt.

Return Value

The product of the numbers in a and b. At least one of a and b should be a variable of type Fixed.

The returned value is in the format of a LongInt if one of a or b is a LongInt. It is a Fract number if one of a or b is Fract. It is a Fixed number if both a and b are Fixed numbers.

Overflows are set to the maximum representable value with the correct sign ($80000000 for negative results and $7FFFFFFF for positive results).

Availability
Declared In
FixMath.h

FixRatio

Obtains the Fixed equivalent of a fraction.

Fixed FixRatio (
   short numer,
   short denom
);

Parameters
numer

The numerator of the fraction.

denom

The denominator of the fraction.

Return Value

The Fixed equivalent of the fraction numer/denom.

Availability
Declared In
FixMath.h

FixRound

Rounds a fixed-point number to the nearest integer.

short FixRound (
   Fixed x
);

Parameters
x

The Fixed number to be rounded.

Return Value

The Integer number nearest the Fixed number x. If the value is halfway between two integers (0.5), it is rounded up. Thus, 4.5 is rounded to 5, and –3.5 is rounded to –3.

Discussion

To round a negative Fixed number so that values halfway between two integers are rounded to the number with the higher absolute value, negate the number, round it, and then negate it again.

Availability
Declared In
FixMath.h

FloatToFixed

Converts a float number to a Fixed number. 

Fixed FloatToFixed (
   float x
);

Parameters
x

The float number to be converted.

Return Value

The Fixed equivalent of the float number.

Discussion

This function is implemented as an inline macro.

Availability
Declared In
FixMath.h

FloatToFract

Converts a float number to a Fract number. 

Fract FloatToFract (
   float x
);

Parameters
x

The float number to be converted.

Return Value

The Fract equivalent of the float number.

Discussion

This function is implemented as an inline macro.

Availability
Declared In
FixMath.h

floor

double_t floor (
   double_t x
);

Parameters
x
Return Value
Availability
Declared In
fp.h

fmax

double_t fmax (
   double_t x,
   double_t y
);

Parameters
x
y
Return Value
Availability
Declared In
fp.h

fmin

double_t fmin (
   double_t x,
   double_t y
);

Parameters
x
y
Return Value
Availability
Declared In
fp.h

fmod

double_t fmod (
   double_t x,
   double_t y
);

Parameters
x
y
Return Value
Availability
Declared In
fp.h

fpclassify

long fpclassify (
   float x
);

Parameters
x

A value of type float or double.

Return Value

Returns one of the FP_ values. See FP_SNAN.

Discussion

This function is implemented as an inline macro.

Availability
Declared In
fp.h

Frac2Fix

Converts a Fract number to a Fixed number.

Fixed Frac2Fix (
   Fract x
);

Parameters
x

The Fract number to be converted to a Fixed number.

Return Value

The Fixed number that best approximates the Fract number x.

Availability
Declared In
FixMath.h

Frac2X

Converts a Fract number to an Extended number.

double Frac2X (
   Fract x
);

Parameters
x

The Fract number to be converted to an Extended number.

Return Value

The Extended equivalent of the Fract number x.

Availability
Declared In
FixMath.h

FracCos

Obtains a fast approximation of the cosine of a Fixed number.

Fract FracCos (
   Fixed x
);

Parameters
x

The Fixed number expressed in radians, whose cosine is to be calculated.

Return Value

The cosine, expressed in radians, of the Fixed number x.

Discussion

The approximation of p/4 used to compute the cosine is the hexadecimal value 0.C910, making the approximation of p equal to 3.1416015625, while p itself equals 3.14159265.... Despite the approximation of p, the cosine value obtained is usually correct to several decimal places.

Availability
Declared In
FixMath.h

FracDiv

Divides two variables of the same type (Fract, Fixed, or LongInt) or to divide a LongInt or Fixed number by a Fract number.

Fract FracDiv (
   Fract x,
   Fract y
);

Parameters
x

The first operand, which can be a variable of type Fract or a variable of type Fixed or LongInt.

y

The second operand, which can be a variable of type Fract or a variable of the same type as the variable in parameter a.

Return Value

The quotient of the numbers in a and b. If the b parameter is in the format of a Fract number, then the a parameter can be in the format of a Fract, a Fixed, or a LongInt number. If the b parameter is in the format of a Fixed or a LongInt number, then the a parameter must be in the same format.

The returned value is in the format of a Fract number if a and b are both Fract numbers, both Fixed numbers, or both LongInt numbers. Otherwise, the returned value is in the same format as the number in the a parameter.

Division by zero results in $8000000 if a is negative, and $7FFFFFFF otherwise; thus the special case 0/0 yields $7FFFFFFF.

Availability
Declared In
FixMath.h

FracMul

Multiplies a variable of type Fract with another variable of type Fract or with a variable of type Fixed or LongInt.

Fract FracMul (
   Fract x,
   Fract y
);

Parameters
x

The first operand, which can be a variable of type Fract or a variable of type Fixed or LongInt.

y

The second operand, which can be a variable of type Fract or a variable of type Fixed or LongInt.

Return Value

The product of the numbers in a and b. At least one of a or b should be a variable of type Fract.

The returned value is in the format of a LongInt number if one of a and b is a LongInt number. It is a Fixed number if one of a or b is a Fixed number. It is a Fract number if both a and b are Fract numbers.

Overflows are set to the maximum representable value with the correct sign ($80000000 for negative results and $7FFFFFFF for positive results).

Availability
Declared In
FixMath.h

FracSin

Obtains a fast approximation of the sine of a Fixed number.

Fract FracSin (
   Fixed x
);

Parameters
x

The Fixed number expressed in radians, whose sine is to be calculated.

Return Value

The sine, expressed in radians, of the Fixed number x.

Discussion

The approximation of p/4 used to compute the sine is the hexadecimal value 0.C910, making the approximation of p equal to 3.1416015625, while p itself equals 3.14159265.... Despite the approximation of p, the sine value obtained is usually correct to several decimal places.

Availability
Declared In
FixMath.h

FracSqrt

Obtains the square root of a Fract number.

Fract FracSqrt (
   Fract x
);

Parameters
x

The Fract number to obtain a square root of. This parameter is interpreted as being unsigned in the range 0 through 4 – 2–30, inclusive. That is, the bit of the Fract number that ordinarily has weight -2 is instead interpreted as having weight 2.

Return Value

The square root of the specified Fract number. The result is unsigned in the range 0 through 2, inclusive.

Availability
Declared In
FixMath.h

FractToFloat

Converts a Fract number to a float number. 

float FixedToFract (
   Fract x
);

Parameters
x

The Fract number to be converted.

Return Value

The float equivalent of the Fract number.

Discussion

This function is implemented as an inline macro.

Availability
Declared In
FixMath.h

frexp

double_t frexp (
   double_t x,
   int *exponent
);

Parameters
x
exponent
Return Value
Availability
Declared In
fp.h

gamma

double_t gamma (
   double_t x
);

Parameters
x
Return Value
Availability
Declared In
fp.h

HiWord

Obtains the high-order word of a long word. 

SInt16 HiWord (
   SInt32 x
);

Parameters
x

The long word whose high word is to be returned.

Return Value

The high-order word of the long word specified by the x parameter.

Discussion

One use of this function is to obtain the integral part of a fixed-point number.

To copy a range of bytes from one memory location to another, you should ordinarily use the Memory Manager function, BlockMove.

Availability
Declared In
ToolUtils.h

hypot

double_t hypot (
   double_t x,
   double_t y
);

Parameters
x
y
Return Value
Availability
Declared In
fp.h

isfinite

long isfinite (
   float x
);

Parameters
x

A value of type float or double.

Return Value

Returns a non-zero value only if the argument is finite.

Discussion

This function is implemented as an inline macro.

Availability
Declared In
fp.h

isnan

long isnan (
   float x
);

Parameters
x

A value of type float or double.

Return Value

Returns a non-zero value only if the argument is not a number (NaN).

Discussion

This function is implemented as an inline macro.

Availability
Declared In
fp.h

isnormal

long isnormal (
   float x
);

Parameters
x

A value of type float or double.

Return Value

Returns a non-zero value only if the argument is normalized.

Discussion

This function is implemented as an inline macro.

Availability
Declared In
fp.h

ldexp

double_t ldexp (
   double_t x,
   int n
);

Parameters
x
n
Return Value
Availability
Declared In
fp.h

lgamma

double_t lgamma (
   double_t x
);

Parameters
x
Return Value
Availability
Declared In
fp.h

log

double_t log (
   double_t x
);

Parameters
x
Return Value
Availability
Declared In
fp.h

log10

double_t log10 (
   double_t x
);

Parameters
x
Return Value
Availability
Declared In
fp.h

log1p

double_t log1p (
   double_t x
);

Parameters
x
Return Value
Availability
Declared In
fp.h

log2

double_t log2 (
   double_t x
);

Parameters
x
Return Value
Availability
Declared In
fp.h

logb

double_t logb (
   double_t x
);

Parameters
x
Return Value
Availability
Declared In
fp.h