Tcl Fixed Point Math API Library Module

The Tcl fixed point math API library module has the file name fxp.tcl. 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 integers. The position of the decimal point, the number as a string and the current value as a integer are stored in a list called the fxp list. 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 list is the same as the integer calculation range available in Tcl. This API has been coded to make use of the logging 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 procedures 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_get_list
- fxp_debug
- fxp_remove_decimal

# Module Dependencies

The following modules are required along with this module:

- parse.tcl
- logger.tcl
- logman.tcl

# Module Definition Files

This module requires the definition file:

- stdhead.tcl

# Module Procedures

## fxp_iconv

    Declaration  : proc fxp_iconv {cval}
    Parameters   :
          Name   : cval
          Type   : floating point number as a string
    Description  : input number

    Returns      : fxp list upon success, empty string otherwise

This procedure will perform an input conversion on a floating point number.

## fxp_oconv

    Declaration  : proc fxp_oconv {fxp_list tscale outstr}
    Parameters   :
          Name   : fxp_list
          Type   : fxp list
    Description  : fixed point input

          Name   : tscale
          Type   : positive integer
    Description  : output scale

          Name   : outstr
          Type   : floating point number as string
    Description  : output result

    Returns      : 1 upon success, 0 otherwise

This procedure 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

    Declaration  : proc fxp_add {ad1 ad2}
    Parameters   :
          Name   : ad1
          Type   : fxp list
    Description  : first operand

          Name   : ad2
          Type   : fxp list
    Description  : second operand

    Returns      : fxp list upon success, empty string otherwise

This procedure will add two fixed point numbers.

## fxp_sub

    Declaration  : proc fxp_sub {ad1 ad2}
    Parameters   :
          Name   : ad1
          Type   : fxp list
    Description  : first operand

          Name   : ad2
          Type   : fxp list
    Description  : second operand

    Returns      : fxp list upon success, empty string otherwise

This procedure will subtract two fixed point numbers. Note that the second operand is subtracted from the first operand.

## fxp_mul

    Declaration  : proc fxp_mul {ad1 ad2}
    Parameters   :
          Name   : ad1
          Type   : fxp list
    Description  : first operand

          Name   : ad2
          Type   : fxp list
    Description  : second operand

    Returns      : fxp list upon success, empty string otherwise

This procedure will multiply two fixed point numbers. Note that the first operand is multiplied by the second operand.

## fxp_div

    Declaration  : proc fxp_div {ad1 ad2}
    Parameters   :
          Name   : ad1
          Type   : fxp list
    Description  : first operand

          Name   : ad2
          Type   : fxp list
    Description  : second operand

    Returns      : fxp list upon success, empty string otherwise

This procedure will divide two fixed point numbers. Note that the first operand is divided by the second operand.

## fxp_eq

    Declaration  : proc fxp_eq {fxp1 fxp2}
    Parameters   :
          Name   : fxp1
          Type   : fxp list
    Description  : first operand

          Name   : fxp2
          Type   : fxp list
    Description  : second operand

    Returns      : 1 if equal, 0 otherwise

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

## fxp_lt

    Declaration  : proc fxp_lt {fxp1 fxp2}
    Parameters   :
          Name   : fxp1
          Type   : fxp list
    Description  : first operand

          Name   : fxp2
          Type   : fxp list
    Description  : second operand

    Returns      : 1 if first operand is less than second operand, 0 otherwise

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

## fxp_gt

    Declaration  : proc fxp_gt {fxp1 fxp2}
    Parameters   :
          Name   : fxp1
          Type   : fxp list
    Description  : first operand

          Name   : fxp2
          Type   : fxp list
    Description  : second operand

    Returns      : 1 if first operand is greater than second operand, 0 otherwise

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

## fxp_le

    Declaration  : proc fxp_le {fxp1 fxp2}
    Parameters   :
          Name   : fxp1
          Type   : fxp list
    Description  : first operand

          Name   : fxp2
          Type   : fxp list
    Description  : second operand

    Returns      : 1 if first operand is less than or equal to the second operand, 0 otherwise

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

## fxp_ge

    Declaration  : proc fxp_ge {fxp1 fxp2}
    Parameters   :
          Name   : fxp1
          Type   : fxp list
    Description  : first operand

          Name   : fxp2
          Type   : fxp list
    Description  : second operand

    Returns      : 1 if first operand is greater than or equal to the second operand, 0 otherwise

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

## fxp_math

    Declaration  : proc fxp_math {ad1 ad2 opcode}
    Parameters   :
          Name   : ad1
          Type   : fxp list
    Description  : first operand

          Name   : ad2
          Type   : fxp list
    Description  : second operand

          Name   : opcode
          Type   : integer
    Description  : math operation code

    Returns      : fxp list containing the result

This procedure will perform math on two fixed point numbers and return the result.

## fxp_comp

    Declaration  : proc fxp_comp {ad1 ad2 opcode}
    Parameters   :
          Name   : ad1
          Type   : fxp list
    Description  : first operand

          Name   : ad2
          Type   : fxp list
    Description  : second operand

          Name   : opcode
          Type   : integer
    Description  : comparison operation code

    Returns      : 1 upon successful comparison, 0 otherwise

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

## fxp_scale

    Declaration  : proc fxp_scale {fxp_list tscale}
    Parameters   :
          Name   : fxp_list
          Type   : fxp list
    Description  : input fixed point number

          Name   : tscale
          Type   : integer
    Description  : desired scale/precision

    Returns      : 1 upon success, 0 otherwise

This procedure 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_get_list

    Declaration  : proc fxp_get_list {fxp_list out_fxp out_scale}
    Parameters   :
          Name   : fxp_list
          Type   : fxp list
    Description  : input fixed point number

          Name   : out_fxp
          Type   : fxp list
    Description  : output fixed point number

          Name   : out_scale
          Type   : integer
    Description  : output scale/precision

    Returns      : 1 upon success, 0 otherwise

This procedure will extract the number and the scale from the input fixed point number and place them into the output fixed point number and the output scale/precision.

## fxp_debug

    Declaration  : proc fxp_debug {f1}
    Parameters   :
          Name   : f1
          Type   : fxp list
    Description  : input fixed point number

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

## fxp_remove_decimal

    Declaration  : proc fxp_remove_decimal {cfin}
    Parameters   :
          Name   : cfin
          Type   : floating point number as a string
    Description  : input floating-point number in string form

    Returns      : integer as string upon success, empty string otherwise

This procedure will return the input floating-point number in string form removing the decimal point.

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

Copyright © 2005-2006 Future Lab, Last Updated Jul 01, 2006