Fixed Point Math API Library Module

The fixed point math API library module has the file name fxp.c. This module performs basic math operations and comparisons on floating point numbers using fixed point math. Floating point numbers are input in string form and stored as long integers. The position of the decimal point, the number as a string and the current value as a long are stored in a structure called fxp. The current position of the decimal point from the right side of the string is referred to in this document as the scale.

The calculation range of an fxp structure is the same as a signed long integer. All fxp structures are dynamically allocated and must be de-allocated using fxp_free only. This API has been coded to make use of the log manager API if it has been enabled.

Please see my floating point polemic paper for reasons why I use fixed point arithmetic and never use floating point.

Here is a list of functions in the fixed-point math API library module:

- fxp_iconv
- fxp_oconv
- fxp_add
- fxp_sub
- fxp_mul
- fxp_div
- fxp_eq
- fxp_lt
- fxp_gt
- fxp_le
- fxp_ge
- fxp_math
- fxp_comp
- fxp_scale
- fxp_free
- fxp_dup
- fxp_new
- fxp_debug
- fxp_remove_decimal

# Module Dependencies

The following modules are required along with this module:

- parse.c
- logger.c
- logman.c

# Module Header Files

This module requires the header file:

- stdhead.h

# Module Functions

## fxp_iconv

    Prototype  : struct fxp *fxp_iconv(char *cval)
    Parameters :
          Name : cval
    Description: floating-point number in string form

    Returns    : a pointer to a newly allocated fxp structure

This function will perform an input conversion on a floating point number. This function will dynamically create an fxp structure. It is the responsibility of the caller to de-allocate the structure after use.

## fxp_oconv

    Prototype  : int fxp_oconv(struct fxp *tfxp, int tscale, char *outstr)
    Parameters :
          Name : tfxp
    Description: fixed point input

          Name : tscale
    Description: output scale

          Name : outstr
    Description: output result

    Returns    : TRUE upon success, FALSE otherwise

This function will perform an output conversion on a fixed point number. Upon success, the string output result will be loaded with the result. An attempt is made to round the result to the precision specified by the output scale.

## fxp_add

    Prototype  : struct fxp *fxp_add(struct fxp *ad1, struct fxp *ad2)
    Parameters :
          Name : ad1
    Description: first operand

          Name : ad2
    Description: second operand

    Returns    : a pointer to a newly allocated fxp structure

This function will add two fixed point numbers. A new fxp structure will be dynamically allocated for the result. This must be de-allocated by the caller.

## fxp_sub

    Prototype  : struct fxp *fxp_sub(struct fxp *ad1, struct fxp *ad2)
    Parameters :
          Name : ad1
    Description: first operand

          Name : ad2
    Description: second operand

    Returns    : a pointer to a newly allocated fxp structure

This function will subtract two fixed point numbers. A new fxp structure will be dynamically allocated for the result. This must be de-allocated by the caller. Note that the second operand is subtracted from the first operand.

## fxp_mul

    Prototype  : struct fxp *fxp_mul(struct fxp *ad1, struct fxp *ad2)
    Parameters :
          Name : ad1
    Description: first operand

          Name : ad2
    Description: second operand

    Returns    : a pointer to a newly allocated fxp structure

This function will multiply two fixed point numbers. A new fxp structure will be dynamically allocated for the result. This must be de-allocated by the caller. Note that the first operand is multiplied by the second operand.

## fxp_div

    Prototype  : struct fxp *fxp_div(struct fxp *ad1, struct fxp *ad2)
    Parameters :
          Name : ad1
    Description: first operand

          Name : ad2
    Description: second operand

    Returns    : a pointer to a newly allocated fxp structure

This function will divide two fixed point numbers. A new fxp structure will be dynamically allocated for the result. This must be de-allocated by the caller. Note that the first operand is divided by the second operand.

## fxp_eq

    Prototype  : int fxp_eq(struct fxp *fxp1, struct fxp *fxp2)
    Parameters :
          Name : fxp1
    Description: first operand

          Name : fxp2
    Description: second operand

    Returns    : TRUE if equal, FALSE otherwise

This function will perform an equality test of two fixed point numbers.

## fxp_lt

    Prototype  : int fxp_lt(struct fxp *fxp1, struct fxp *fxp2)
    Parameters :
          Name : fxp1
    Description: first operand

          Name : fxp2
    Description: second operand

    Returns    : TRUE if first operand is less than
    second operand, FALSE otherwise

This function will determine whether one fixed point number is less than the other.

## fxp_gt

    Prototype  : int fxp_gt(struct fxp *fxp1, struct fxp *fxp2)
    Parameters :
          Name : fxp1
    Description: first operand

          Name : fxp2
    Description: second operand

    Returns    : TRUE if first operand is greater than
    second operand, FALSE otherwise

This function will determine whether one fixed point number is greater than the other.

## fxp_le

    Prototype  : int fxp_le(struct fxp *fxp1, struct fxp *fxp2)
    Parameters :
          Name : fxp1
    Description: first operand

          Name : fxp2
    Description: second operand

    Returns    : TRUE if first operand is less than or equal to the
    second operand, FALSE otherwise

This function will determine whether one fixed point number is less than or equal to the other.

## fxp_ge

    Prototype  : int fxp_ge(struct fxp *fxp1, struct fxp *fxp2)
    Parameters :
          Name : fxp1
    Description: first operand

          Name : fxp2
    Description: second operand

    Returns    : TRUE if first operand is greater than or equal to
    the second operand, FALSE otherwise

This function will determine whether one fixed point number is greater than or equal to the other.

## fxp_math

    Prototype  : static struct fxp *fxp_math(struct fxp *ad1, struct fxp *ad2,
                                             int opcode)
    Parameters :
          Name : ad1
    Description: first operand

          Name : ad2
    Description: second operand

          Name : opcode
    Description: math operation code

    Returns    : a pointer to a newly allocated fxp structure

This private function will perform math on two fixed point numbers and return the result. A new fxp structure will be dynamically allocated for the result. This must be de-allocated by the caller.

## fxp_comp

    Prototype  : static struct fxp *fxp_comp(struct fxp *ad1, struct fxp *ad2,
                                             int opcode)
    Parameters :
          Name : ad1
    Description: first operand

          Name : ad2
    Description: second operand

          Name : opcode
    Description: comparison operation code

    Returns    : TRUE upon successful comparison, FALSE otherwise

This private function will perform a comparison of two fixed point numbers and return the result.

## fxp_scale

    Prototype  : int fxp_scale(struct fxp *tfxp, int tscale)
    Parameters :
          Name : tfxp
    Description: input fixed-point number

          Name : tscale
    Description: desired scale/precision

    Returns    : TRUE upon success, FALSE otherwise

This function will change the scale of the input fixed point number. Digits will be added or taken away from the right side of the number.

## fxp_free

    Prototype  : void fxp_free(struct fxp *tfxp)
    Parameters :
          Name : tfxp
    Description: input fixed-point number

This function will de-allocate all dynamic memory used by a single fxp structure.

## fxp_dup

    Prototype  : struct fxp *fxp_dup(struct fxp *tfxp)
    Parameters :
          Name : tfxp
    Description: input fixed-point number

    Returns    : a pointer to a newly allocated fxp structure

This function will duplicate an fxp structure.

## fxp_new

    Prototype  : static struct fxp *fxp_new(void)

    Returns    : a pointer to a newly allocated fxp structure

This private function will create a new fxp structure. Structure will be initialized.

## fxp_debug

    Prototype  : void fxp_debug(struct fxp *f1)
    Parameters :
          Name : f1
    Description: input fixed-point number

This function will output the contents of an fxp structure to the logging manager. No data will be output unless the logging manager has been started by calling the function logman_start.

## fxp_remove_decimal

    Prototype  : void fxp_remove_decimal(char *cfin, char *cfout)
    Parameters :
          Name : cfin
    Description: input floating-point number in string form

          Name : cfout
    Description: output number in string form

This function will copy the input floating-point number in string form removing the decimal point. Function returns the input floating-point number in string form (minus the decimal point) in the output number in string form upon success.

Goto Top | GPL Software Overview | GPL Library
Future Lab Home | Contact Webmaster | Feedback

Copyright © 2002-2006 Future Lab, Last Updated Jun 30, 2006