Overview

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:

• Perform low-level logical manipulation of bits and bytes when using a compiler that does not directly support such manipulations.

• Save disk space by using simple compression and decompression routines.

• Obtain a pseudorandom number.

• Perform mathematical operations with two fixed-point data types supported directly by the Operating System.

• Convert numeric variables of different types.

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

• Fix2Frac Deprecated in OS X v10.8
• Fix2Long Deprecated in OS X v10.8
• Frac2Fix Deprecated in OS X v10.8
• Long2Fix Deprecated in OS X v10.8

Converting Between Fixed-Point and Floating-Point Values

• FixedToFloat
• FractToFloat
• FloatToFixed
• FloatToFract
• Fix2X Deprecated in OS X v10.8
• Frac2X Deprecated in OS X v10.8
• X2Fix Deprecated in OS X v10.8
• X2Frac Deprecated in OS X v10.8

Converting Between Fixed-Point and Integral Values

• FixRatio Deprecated in OS X v10.8
• FixRound Deprecated in OS X v10.8

Getting and Setting Memory Values

• HiWord
• LoWord

Multiplying and Dividing Fixed-Point Numbers

• FixDiv Deprecated in OS X v10.8
• FixMul Deprecated in OS X v10.8
• FracDiv Deprecated in OS X v10.8
• FracMul Deprecated in OS X v10.8

Performing Calculations on Fixed-Point Numbers

• FixATan2 Deprecated in OS X v10.8
• FracCos Deprecated in OS X v10.8
• FracSin Deprecated in OS X v10.8
• FracSqrt Deprecated in OS X v10.8

Performing Logical Operations

• BitAnd Deprecated in OS X v10.8
• BitNot Deprecated in OS X v10.8
• BitOr Deprecated in OS X v10.8
• BitShift Deprecated in OS X v10.8
• BitXor Deprecated in OS X v10.8

Testing and Setting Bits

• BitClr Deprecated in OS X v10.8
• BitSet Deprecated in OS X v10.8
• BitTst Deprecated in OS X v10.8

Miscellaneous Functions

• acos
• acosh
• asin
• asinh
• atan
• atan2
• atanh
• ceil
• copysign
• cos
• cosh
• erf
• erfc
• exp
• exp2
• expm1
• fabs
• fdim
• floor
• fmax
• fmin
• fmod
• fpclassify
• frexp
• gamma
• hypot
• isfinite
• isnan
• isnormal
• ldexp
• lgamma
• log
• log10
• log1p
• log2
• logb
• modf
• modff
• nan
• nanf
• nearbyint
• nextafterd
• nextafterf
• pi
• pow
• remainder
• remquo
• rint
• rinttol
• round
• roundtol
• S32Set
• S64Absolute
• S64Add
• S64And
• S64BitwiseAnd
• S64BitwiseEor
• S64BitwiseNot
• S64BitwiseOr
• S64Div
• S64Divide
• S64Eor
• S64Max
• S64Min
• S64Multiply
• S64Negate
• S64Not
• S64Or
• S64Set
• S64SetU
• S64ShiftLeft
• S64ShiftRight
• S64Subtract
• scalb
• signbit
• sin
• sinh
• SInt64ToUInt64
• sqrt
• tan
• tanh
• trunc
• U32SetU
• U64Add
• U64And
• U64BitwiseAnd
• U64BitwiseEor
• U64BitwiseNot
• U64BitwiseOr
• U64Div
• U64Divide
• U64Eor
• U64Max
• U64Multiply
• U64Not
• U64Or
• U64Set
• U64SetU
• U64ShiftLeft
• U64ShiftRight
• U64Subtract
• UInt64ToSInt64
• annuity Deprecated in OS X v10.8
• compound Deprecated in OS X v10.8
• dec2f Deprecated in OS X v10.8
• dec2l Deprecated in OS X v10.8
• dec2num Deprecated in OS X v10.8
• dec2s Deprecated in OS X v10.8
• dec2str Deprecated in OS X v10.8
• dtox80 Deprecated in OS X v10.8
• num2dec Deprecated in OS X v10.8
• randomx Deprecated in OS X v10.8
• relation Deprecated in OS X v10.8
• S64Compare Deprecated in OS X v10.8
• str2dec Deprecated in OS X v10.8
• U64Compare Deprecated in OS X v10.8
• WideAdd Deprecated in OS X v10.8
• WideBitShift Deprecated in OS X v10.8
• WideCompare Deprecated in OS X v10.8
• WideDivide Deprecated in OS X v10.8
• WideMultiply Deprecated in OS X v10.8
• WideNegate Deprecated in OS X v10.8
• WideShift Deprecated in OS X v10.8
• WideSquareRoot Deprecated in OS X v10.8
• WideSubtract Deprecated in OS X v10.8
• WideWideDivide Deprecated in OS X v10.8
• x80tod Deprecated in OS X v10.8

Functions

acos

double_t acos (
   double_t x
);

acosh

double_t acosh (
   double_t x
);

asin

double_t asin (
   double_t x
);

asinh

double_t asinh (
   double_t x
);

atan

double_t atan (
   double_t x
);

atan2

double_t atan2 (
   double_t y,
   double_t x
);

atanh

double_t atanh (
   double_t x
);

ceil

double_t ceil (
   double_t x
);

copysign

double_t copysign (
   double_t x,
   double_t y
);

cos

double_t cos (
   double_t x
);

cosh

double_t cosh (
   double_t x
);

erf

double_t erf (
   double_t x
);

erfc

double_t erfc (
   double_t x
);

exp

double_t exp (
   double_t x
);

exp2

double_t exp2 (
   double_t x
);

expm1

double_t expm1 (
   double_t x
);

fabs

double_t fabs (
   double_t x
);

fdim

double_t fdim (
   double_t x,
   double_t y
);

FixedToFloat

Converts a Fixed number to a float number.

float FixedToFloat (
   Fixed x
);

FloatToFixed

Converts a float number to a Fixed number.

Fixed FloatToFixed (
   float x
);

FloatToFract

Converts a float number to a Fract number.

Fract FloatToFract (
   float x
);

floor

double_t floor (
   double_t x
);

fmax

double_t fmax (
   double_t x,
   double_t y
);

fmin

double_t fmin (
   double_t x,
   double_t y
);

fmod

double_t fmod (
   double_t x,
   double_t y
);

fpclassify

long fpclassify (
   float x
);

FractToFloat

Converts a Fract number to a float number.

float FixedToFract (
   Fract x
);

frexp

double_t frexp (
   double_t x,
   int *exponent
);

gamma

double_t gamma (
   double_t x
);

HiWord

Obtains the high-order word of a long word.

SInt16 HiWord (
   SInt32 x
);

hypot

double_t hypot (
   double_t x,
   double_t y
);

isfinite

long isfinite (
   float x
);

isnan

long isnan (
   float x
);

isnormal

long isnormal (
   float x
);

ldexp

double_t ldexp (
   double_t x,
   int n
);

lgamma

double_t lgamma (
   double_t x
);

log

double_t log (
   double_t x
);

log10

double_t log10 (
   double_t x
);

log1p

double_t log1p (
   double_t x
);

log2

double_t log2 (
   double_t x
);

logb

double_t logb (
   double_t x
);

LoWord

Obtains the low-order word of a long word.

SInt16 LoWord (
   SInt32 x
);

modf

double_t modf (
   double_t x,
   double_t *iptr
);

modff

float modff (
   float x,
   float *iptrf
);

nan

double nan (
   const char *tagp
);

nanf

float nanf (
   const char *tagp
);

nearbyint

double_t nearbyint (
   double_t x
);

nextafterd

double nextafterd (
   double x,
   double y
);

nextafterf

float nextafterf (
   float x,
   float y
);

pi

pi ();

pow

double_t pow (
   double_t x,
   double_t y
);

remainder

double_t remainder (
   double_t x,
   double_t y
);

remquo

double_t remquo (
   double_t x,
   double_t y,
   int *quo
);

rint

double_t rint (
   double_t x
);

rinttol

long rinttol (
   double_t x
);

round

double_t round (
   double_t x
);

roundtol

long roundtol (
   double_t round
);

S32Set

SInt32 S32Set (
   SInt64 value
);

S64Absolute

SInt64 S64Absolute (
   SInt64 value
);

S64Add

SInt64 S64Add (
   SInt64 left,
   SInt64 right
);

S64And

Boolean S64And (
   SInt64 left,
   SInt64 right
);

S64BitwiseAnd

SInt64 S64BitwiseAnd (
   SInt64 left,
   SInt64 right
);

S64BitwiseEor

SInt64 S64BitwiseEor (
   SInt64 left,
   SInt64 right
);

S64BitwiseNot

SInt64 S64BitwiseNot (
   SInt64 value
);

S64BitwiseOr

SInt64 S64BitwiseOr (
   SInt64 left,
   SInt64 right
);

S64Div

SInt64 S64Div (
   SInt64 dividend,
   SInt64 divisor
);

S64Divide

SInt64 S64Divide (
   SInt64 dividend,
   SInt64 divisor,
   SInt64 *remainder
);

S64Eor

Boolean S64Eor (
   SInt64 left,
   SInt64 right
);

S64Max

SInt64 S64Max (
   void
);

S64Min

SInt64 S64Min (
   void
);

S64Multiply

SInt64 S64Multiply (
   SInt64 left,
   SInt64 right
);

S64Negate

SInt64 S64Negate (
   SInt64 value
);

S64Not

Boolean S64Not (
   SInt64 value
);

S64Or

Boolean S64Or (
   SInt64 left,
   SInt64 right
);

S64Set

SInt64 S64Set (
   SInt32 value
);

S64SetU

SInt64 S64SetU (
   UInt32 value
);

S64ShiftLeft

SInt64 S64ShiftLeft (
   SInt64 value,
   UInt32 shift
);

S64ShiftRight

SInt64 S64ShiftRight (
   SInt64 value,
   UInt32 shift
);

S64Subtract

SInt64 S64Subtract (
   SInt64 left,
   SInt64 right
);

scalb

double_t scalb (
   double_t x,
   _scalb_n_type n
);

signbit

long signbit (
   float x
);

sin

double_t sin (
   double_t x
);

sinh

double_t sinh (
   double_t x
);

SInt64ToUInt64

UInt64 SInt64ToUInt64 (
   SInt64 value
);

sqrt

double_t sqrt (
   double_t x
);

tan

double_t tan (
   double_t x
);

tanh

double_t tanh (
   double_t x
);

trunc

_trunc_return_type trunc (
   double_t x
);

U32SetU

UInt32 U32SetU (
   UInt64 value
);

U64Add

UInt64 U64Add (
   UInt64 left,
   UInt64 right
);

U64And

Boolean U64And (
   UInt64 left,
   UInt64 right
);

U64BitwiseAnd

UInt64 U64BitwiseAnd (
   UInt64 left,
   UInt64 right
);

U64BitwiseEor

UInt64 U64BitwiseEor (
   UInt64 left,
   UInt64 right
);

U64BitwiseNot

UInt64 U64BitwiseNot (
   UInt64 value
);

U64BitwiseOr

UInt64 U64BitwiseOr (
   UInt64 left,
   UInt64 right
);

U64Div

Under evaluation

UInt64 U64Div (
   UInt64 dividend,
   UInt64 divisor
);

U64Divide

UInt64 U64Divide (
   UInt64 dividend,
   UInt64 divisor,
   UInt64 *remainder
);

U64Eor

Boolean U64Eor (
   UInt64 left,
   UInt64 right
);

U64Max

UInt64 U64Max (
   void
);

U64Multiply

UInt64 U64Multiply (
   UInt64 left,
   UInt64 right
);

U64Not

Boolean U64Not (
   UInt64 value
);

U64Or

Boolean U64Or (
   UInt64 left,
   UInt64 right
);

U64Set

UInt64 U64Set (
   SInt32 value
);

U64SetU

UInt64 U64SetU (
   UInt32 value
);

U64ShiftLeft

UInt64 U64ShiftLeft (
   UInt64 value,
   UInt32 shift
);

U64ShiftRight

UInt64 U64ShiftRight (
   UInt64 value,
   UInt32 shift
);

U64Subtract

UInt64 U64Subtract (
   UInt64 left,
   UInt64 right
);

UInt64ToSInt64

SInt64 UInt64ToSInt64 (
   UInt64 value
);

Data Types

decform

struct decform {
   char style;
   char unused;
   short digits;
};
typedef struct decform decform;

Fields

style

unused

digits

decimal

struct decimal {
   char sgn
   char unused
   short exp
   struct {
      unsigned char length;
      unsigned char text[36];
      unsigned char pad;
   } sig;
};
typedef struct decimal decimal;

Fields

sgn

unused

exp

length

text

pad

double_t

typedef double double_t;

fenv_t

typedef SInt32 fenv_t;

fexcept_t

typedef SInt32 fexcept_t;

Fixed

Defines a data type for fixed-point decimal numbers.

typedef SInt32 Fixed;

Discussion

This data type uses a 16-bit signed integer and a 16-bit fraction to represent fixed-point decimal numbers in the interval:

For example, the number 1.5 would be represented as 0x00018000, and the number -1.3 would be represented as 0xFFFEB334. To convert numbers between Fixed and float, you can use the functions FixedToFloat and FloatToFixed.

Fract

Defines a high-precision data type for fixed-point decimal numbers.

typedef SInt32 Fract;

Discussion

This data type uses a 2-bit signed integer and a 30-bit fraction to represent fixed-point decimal numbers in the interval

with higher precision than the Fixed data type. For example, the number 1.5 would be represented as 0x60000000, and the number -1.3 would be represented as 0xACCCCCCD. To convert numbers between Fract and float, you can use the functions FractToFloat and FloatToFract.

float_t

typedef float float_t;

relop

typedef short relop;

_scalb_n_type

typedef int _scalb_n_type;

_trunc_return_type

typedef double_t _trunc_return_type;

Constants

DECSTROUTLEN

enum {
   DECSTROUTLEN = 80
};

Constants

DECSTROUTLEN

FE_INEXACT

Definitions of floating-point exception macros.

enum {
   FE_INEXACT                    = 0x02000000,
   FE_DIVBYZERO                  = 0x04000000,
   FE_UNDERFLOW                  = 0x08000000,
   FE_OVERFLOW                   = 0x10000000,
   FE_INVALID                    = 0x20000000,
   FE_ALL_EXCEPT                 = 0x3E000000
};

Constants

FE_INEXACT

Available in OS X v10.0 through OS X v10.1.

Declared in fenv.h.

FE_DIVBYZERO

Available in OS X v10.0 through OS X v10.1.

Declared in fenv.h.

FE_UNDERFLOW

Available in OS X v10.0 through OS X v10.1.

Declared in fenv.h.

FE_OVERFLOW

Available in OS X v10.0 through OS X v10.1.

Declared in fenv.h.

FE_INVALID

Available in OS X v10.0 through OS X v10.1.

Declared in fenv.h.

FE_ALL_EXCEPT

Available in OS X v10.1 through OS X v10.1.

Declared in fenv.h.

FE_LDBLPREC

enum {
   FE_LDBLPREC = 0,
   FE_DBLPREC = 1,
   FE_FLTPREC = 2
};

Constants

FE_LDBLPREC

FE_DBLPREC

FE_FLTPREC

FE_TONEAREST

Definitions of rounding direction macros.

enum {
   FE_TONEAREST                  = 0x00000000,
   FE_TOWARDZERO                 = 0x00000001,
   FE_UPWARD                     = 0x00000002,
   FE_DOWNWARD                   = 0x00000003
};

Constants

FE_TONEAREST

Available in OS X v10.0 through OS X v10.1.

Declared in fenv.h.

FE_TOWARDZERO

Available in OS X v10.0 through OS X v10.1.

Declared in fenv.h.

FE_UPWARD

Available in OS X v10.0 through OS X v10.1.

Declared in fenv.h.

FE_DOWNWARD

Available in OS X v10.0 through OS X v10.1.

Declared in fenv.h.

fixed1

enum {
   fixed1 = 0x00010000,
   fract1 = 0x40000000,
   positiveInfinity = 0x7FFFFFFF,
   negativeInfinity = 0x80000000
};

Constants

fixed1

fract1

positiveInfinity

negativeInfinity

FP_SNAN

enum {
   FP_SNAN = 0,
   FP_QNAN = 1,
   FP_INFINITE = 2,
   FP_ZERO = 3,
   FP_NORMAL = 4,
   FP_SUBNORMAL = 5
};

Constants

FP_SNAN

Available in OS X v10.0 through OS X v10.1.

Declared in fp.h.

FP_QNAN

Available in OS X v10.0 through OS X v10.1.

Declared in fp.h.

FP_INFINITE

Available in OS X v10.0 through OS X v10.1.

Declared in fp.h.

FP_ZERO

Available in OS X v10.0 through OS X v10.1.

Declared in fp.h.

FP_NORMAL

Available in OS X v10.0 through OS X v10.1.

Declared in fp.h.

FP_SUBNORMAL

Available in OS X v10.0 through OS X v10.1.

Declared in fp.h.

Relational Operator

typedef short relop;
enum {
   GREATERTHAN = 0,
   LESSTHAN = 1,
   EQUALTO = 2,
   UNORDERED = 3
};

Constants

GREATERTHAN

Available in OS X v10.0 and later.

Declared in fp.h.

LESSTHAN

Available in OS X v10.0 and later.

Declared in fp.h.

EQUALTO

Available in OS X v10.0 and later.

Declared in fp.h.

UNORDERED

Available in OS X v10.0 and later.

Declared in fp.h.

SIGDIGLEN

enum {
   SIGDIGLEN = 36
};

Constants

SIGDIGLEN

Special Values

#define HUGE_VAL
#define INFINITY

Constants

HUGE_VAL

Available in OS X v10.0 and later.

Declared in fp.h.

INFINITY

Available in OS X v10.0 and later.

Declared in fp.h.