decimal(3)



math::decimal(3tcl)     Tcl Decimal Arithmetic Library     math::decimal(3tcl)

______________________________________________________________________________

NAME
       math::decimal - General decimal arithmetic

SYNOPSIS
       package require Tcl  ?8.5?

       package require math::decimal  1.0.3

       ::math::decimal::fromstr string

       ::math::decimal::tostr decimal

       ::math::decimal::setVariable variable setting

       ::math::decimal::add a b

       ::math::decimal::+ a b

       ::math::decimal::subtract a b

       ::math::decimal::- a b

       ::math::decimal::multiply a b

       ::math::decimal::* a b

       ::math::decimal::divide a b

       ::math::decimal::/ a b

       ::math::decimal::divideint a b

       ::math::decimal::remainder a b

       ::math::decimal::abs decimal

       ::math::decimal::compare a b

       ::math::decimal::max a b

       ::math::decimal::maxmag a b

       ::math::decimal::min a b

       ::math::decimal::minmag a b

       ::math::decimal::plus a

       ::math::decimal::minus a

       ::math::decimal::copynegate a

       ::math::decimal::copysign a b

       ::math::decimal::is-signed decimal

       ::math::decimal::is-zero decimal

       ::math::decimal::is-NaN decimal

       ::math::decimal::is-infinite decimal

       ::math::decimal::is-finite decimal

       ::math::decimal::fma a b c

       ::math::decimal::round_half_even decimal digits

       ::math::decimal::round_half_up decimal digits

       ::math::decimal::round_half_down decimal digits

       ::math::decimal::round_down decimal digits

       ::math::decimal::round_up decimal digits

       ::math::decimal::round_floor decimal digits

       ::math::decimal::round_ceiling decimal digits

       ::math::decimal::round_05up decimal digits

______________________________________________________________________________

DESCRIPTION
       The  decimal  package provides decimal arithmetic support for both lim-
       ited precision floating point and arbitrary precision  floating  point.
       Additionally, integer arithmetic is supported.

       More  information  and the specifications on which this package depends
       can  be   found   on   the   general   decimal   arithmetic   page   at
       http://speleotrove.com/decimal This package provides for:

       o      A  new data type decimal which is represented as a list contain-
              ing sign, mantissa and exponent.

       o      Arithmetic operations on those decimal numbers such as addition,
              subtraction, multiplication, etc...

       Numbers   are   converted   to   decimal  format  using  the  operation
       ::math::decimal::fromstr.

       Numbers are  converted  back  to  string  format  using  the  operation
       ::math::decimal::tostr.

EXAMPLES
       This  section shows some simple examples. Since the purpose of this li-
       brary is to perform decimal math operations, examples may be  the  sim-
       plest  way  to  learn how to work with it and to see the difference be-
       tween using this package and sticking with expr. Consult the  API  sec-
       tion of this man page for information about individual procedures.

                  package require math::decimal

                  # Various operations on two numbers.
                  # We first convert them to decimal format.
                  set a [::math::decimal::fromstr 8.2]
                  set b [::math::decimal::fromstr .2]

                  # Then we perform our operations. Here we add
                  set c [::math::decimal::+ $a $b]

                  # Finally we convert back to string format for presentation to the user.
                  puts [::math::decimal::tostr $c] ; # => will output 8.4

                  # Other examples
                  #
                  # Subtraction
                  set c [::math::decimal::- $a $b]
                  puts [::math::decimal::tostr $c] ; # => will output 8.0

                  # Why bother using this instead of simply expr?
                  puts [expr {8.2 + .2}] ; # => will output 8.399999999999999
                  puts [expr {8.2 - .2}] ; # => will output 7.999999999999999
                  # See http://speleotrove.com/decimal to learn more about why this happens.

API
       ::math::decimal::fromstr string
              Convert string into a decimal.

       ::math::decimal::tostr decimal
              Convert  decimal  into  a string representing the number in base
              10.

       ::math::decimal::setVariable variable setting
              Sets the variable to setting. Valid variables are:

              o      rounding - Method of  rounding  to  use  during  rescale.
                     Valid   methods   are   round_half_even,   round_half_up,
                     round_half_down,   round_down,   round_up,   round_floor,
                     round_ceiling.

              o      precision - Maximum number of digits allowed in mantissa.

              o      extended  -  Set to 1 for extended mode. 0 for simplified
                     mode.

              o      maxExponent - Maximum value for the exponent. Defaults to
                     999.

              o      minExponent  - Minimum value for the exponent. Default to
                     -998.

       ::math::decimal::add a b

       ::math::decimal::+ a b
              Return the sum of the two decimals a and b.

       ::math::decimal::subtract a b

       ::math::decimal::- a b
              Return the differnece of the two decimals a and b.

       ::math::decimal::multiply a b

       ::math::decimal::* a b
              Return the product of the two decimals a and b.

       ::math::decimal::divide a b

       ::math::decimal::/ a b
              Return the quotient of the division between the two  decimals  a
              and b.

       ::math::decimal::divideint a b
              Return a the integer portion of the quotient of the division be-
              tween decimals a and b

       ::math::decimal::remainder a b
              Return the remainder of the division between the two decimals  a
              and b.

       ::math::decimal::abs decimal
              Return the absolute value of the decimal.

       ::math::decimal::compare a b
              Compare  the two decimals a and b, returning 0 if a == b, 1 if a
              > b, and -1 if a < b.

       ::math::decimal::max a b
              Compare the two decimals a and b, and return a if a >= b, and  b
              if a < b.

       ::math::decimal::maxmag a b
              Compare the two decimals a and b while ignoring their signs, and
              return a if abs(a) >= abs(b), and b if abs(a) < abs(b).

       ::math::decimal::min a b
              Compare the two decimals a and b, and return a if a <= b, and  b
              if a > b.

       ::math::decimal::minmag a b
              Compare the two decimals a and b while ignoring their signs, and
              return a if abs(a) <= abs(b), and b if abs(a) > abs(b).

       ::math::decimal::plus a
              Return the result from ::math::decimal::+ 0 $a.

       ::math::decimal::minus a
              Return the result from ::math::decimal::- 0 $a.

       ::math::decimal::copynegate a
              Returns a with the sign flipped.

       ::math::decimal::copysign a b
              Returns a with the sign set to the sign of the b.

       ::math::decimal::is-signed decimal
              Return the sign of the decimal.  The procedure returns 0 if  the
              number is positive, 1 if it's negative.

       ::math::decimal::is-zero decimal
              Return  true  if  decimal  value is zero, otherwise false is re-
              turned.

       ::math::decimal::is-NaN decimal
              Return true if decimal value is NaN (not  a  number),  otherwise
              false is returned.

       ::math::decimal::is-infinite decimal
              Return true if decimal value is Infinite, otherwise false is re-
              turned.

       ::math::decimal::is-finite decimal
              Return true if decimal value is finite, otherwise false  is  re-
              turned.

       ::math::decimal::fma a b c
              Return  the result from first multiplying a by b and then adding
              c. Rescaling only occurs after completion of all operations.  In
              this  way  the  result may vary from that returned by performing
              the operations individually.

       ::math::decimal::round_half_even decimal digits
              Rounds decimal to digits number of decimal points with the  fol-
              lowing rules: Round to the nearest. If equidistant, round so the
              final digit is even.

       ::math::decimal::round_half_up decimal digits
              Rounds decimal to digits number of decimal points with the  fol-
              lowing rules: Round to the nearest. If equidistant, round up.

       ::math::decimal::round_half_down decimal digits
              Rounds  decimal to digits number of decimal points with the fol-
              lowing rules: Round to the nearest. If equidistant, round down.

       ::math::decimal::round_down decimal digits
              Rounds decimal to digits number of decimal points with the  fol-
              lowing rules: Round toward 0.  (Truncate)

       ::math::decimal::round_up decimal digits
              Rounds  decimal to digits number of decimal points with the fol-
              lowing rules: Round away from 0

       ::math::decimal::round_floor decimal digits
              Rounds decimal to digits number of decimal points with the  fol-
              lowing rules: Round toward -Infinity.

       ::math::decimal::round_ceiling decimal digits
              Rounds  decimal to digits number of decimal points with the fol-
              lowing rules: Round toward Infinity

       ::math::decimal::round_05up decimal digits
              Rounds decimal to digits number of decimal points with the  fol-
              lowing rules: Round zero or five away from 0. The same as round-
              up, except that rounding up only  occurs  if  the  digit  to  be
              rounded  up is 0 or 5, and after overflow the result is the same
              as for round-down.

BUGS, IDEAS, FEEDBACK
       This document, and the package it describes, will  undoubtedly  contain
       bugs and other problems.  Please report such in the category decimal of
       the  Tcllib  Trackers  [http://core.tcl.tk/tcllib/reportlist].   Please
       also  report any ideas for enhancements you may have for either package
       and/or documentation.

       When proposing code changes, please provide unified diffs, i.e the out-
       put of diff -u.

       Note  further  that  attachments  are  strongly  preferred over inlined
       patches. Attachments can be made by going  to  the  Edit  form  of  the
       ticket  immediately  after  its  creation, and then using the left-most
       button in the secondary navigation bar.

KEYWORDS
       decimal, math, tcl

CATEGORY
       Mathematics

COPYRIGHT
       Copyright (c) 2011 Mark Alston <mark at beernut dot com>

tcllib                               1.0.3                 math::decimal(3tcl)

Man(1) output converted with man2html
list of all man pages