RealBigNum.Asielen v113
This page is about the Asielen.RealBigNum
library. It explains what the library does and how it works.
Introduction
This library provides the ability to use any arbitrary length
real numbers in your programs. It provides the ability to do the four
basic operations: addition, subtraction, multiplication, and division
as well as rounding and number comparisons.
Quick Start
Basic Functions:
To get started
using bignums, I have provided some easy to use procs in the
RealBigNum.dm
file.
For each of
these procs:
-
a
and b are numbers that can be in
any format
(num, string, bignum)
- Basic Math
- The float argument in
these
functions is optional and defaults to the global float value (12)
- bAdd(a,b,float=12)
- Add a and b and return a bignum as the result – (a+b)
- bSubtract(a,b,float=12)
- Subtract b from a and return a bignum as the result –
(a-b)
- bMultiply(a,b,float=12)
- Multiply a times b and return a bignum as the result –
(a*b)
- bDivide(a,b,float=12)
- Divide a by b and return a bignum as the result – (a/b)
- Secondary Math
- bGreater(a,b)
- If a > b return 1 else return 0
- bLess(a,b)
- If a < b return 1 else return 0
- bEqual(a,b)
- If a == b return 1 else return 0
- bRound(a,n)
- Round a to n places and return a bignum with the result
- Negative n for rounding to decimal points: -1 =
.1; -3 = .001
- Positive n will round to powers of 10: 1 = 1;
3 = 100
- Ex.
- bRound(123.456,2) = 120
- bRound(123.456,-2) = 123.46
- Display
Numbers
- bString(a)
- Returns number/string/bignum “a” as a string
- bNum(a)
- Returns number/string/bignum “a” as a number
- This is limited by Byond’s internal number limit
Example:
Here are some examples of how to so some simple math and print the
result:
-
Add: 45623 and 62334
- First add the numbers
- var/bignum/result = bAdd(45623, 62334)
- Then convert it to a printable format
- This can be simplified:
- world << bString(bAdd(45623, 62334))
- note: this way you don’t even need to define an extra variable
- Divide 234.23 by -2342.123 and then check to see if it is greater
than 0
- First divide the numbers
- var/bignum/result = bDivide(234.23, -2342.123)
- Then run a comparison
- world << bGreater(result,0)
- note: the comparison functions return 0 or 1 so we don't need to use bString()
- This can be simplified:
- world << bGreater(bDivide(234.23, -2342.123),0)
- Add 123.52 and -123, divide the result by 7, round it to 2 decimal
places
- First add the numbers
- var/bignum/result = bAdd(123.52, -123)
- Then divide
- result = bDivide(result, 7)
- note: as you can see, bDivide() can take either numbers, strings, or
bignums as arguments
- Then round
- world << bString(bRound(result,-2))
- note: negative numbers in bRound(), round to decimal places
- This can be simplified:
- world <<
bString(bRound(bDivide(bAdd(123.52,-123),7),-2))
- note: While this is more compact, it is perhaps less readable. Use
your judgment.
Reference
Gloabal Variables:
- MAXFLOAT - the default number of digits to round to – defaults to 12 places
- DECPOINT - the decimal point recognized – default is "."
- Note,
whatever this is set to is what will be picked up by the BigNum make()
proc as a decimal place, all other characters will be ignored.
- INTSEP - the thousands place divider - default is null, except in demo where it is ","
Gloabal Functions:
- bn_setFloat(float) -
- Used to set the MAXFLOAT value
- Limited to between 0 and 500 by default
- bn_setSeparators(dpoint,isep)
- Used to modify the separators
- dpoint = decimal point
- isep = thousands/integer separator
- Ex: 123,456.789
- "," is the thousangs separator
- "." is the decimal separator
- By default, the decimal separator is "." and the thousands separator is undefined
- Note: this only effects how the numbers are displayed, it doesn't effect how they are stored
bignum definition:
This library creates and makes use of the bignum datum.
This datum definition consists of:
- list/digits
– a list of the digits that represent the
number.
- Note: this
is stored in reverse without the decimal point sign.
- Ex: -1234.5678 is stored as 87654321 in the digits list
- sign
- a Boolean representation of the sign of the number
- TRUE for positive
- FALSE for negative
- Ex: The decimal for -1234.5678 would be FALSE
- decimal
- the number of decimal places in the number
- Ex: The ecimal for -1234.5678 would be 4
- ERROR
- Used to store any errors that may come up
- Ex: If you try to divide by 0 you will get an error
which will be stored here
Creating bignums:
Bignums are created through use of the new() proc. They can be
created from: strings, nums, other bignums, or lists
- Make a bignum from a text
string
- This is the ideal way for initializing a new bignum.
- It was parse out all characters except a sign, numbers,
and a decimal point (it will use the first one it comes across and
ignore the rest)
- var/bignum/b = new(“-123.456”)
- Make a bignum from a num
- This is the least ideal way of making a new bignum
because you are limited by the precision of the built in num type.
- var/bignum/b = new(-123.456)
- Make a bignum from another
bignum
- This is also an ideal way to make a bignum as it will
be an exact copy. However, this is only useful if you already have a
bignum to start with so it is more useful within a function than to
initialize a new bignum.
- var/bignum/b = new(bignum)
- Make a bignum from a list
- This is not an ideal way of making a bignum because you
are limited to a positive integer. (no negative numbers and no decimals)
- The list is assumed to already be in the proper
(reversed) order
- This method should mainly be used to create a bignum
for use within a function
Basic Functions:
These functions simply return data on a bignum datum.
- bn_isbignum(bn)
- Returns 1 if bn is a bignum and 0 if it is not
- bignum.digitsLength()
- Returns the total length of the bignum (integer part +
decimal part) as a num
- bignum.intLength()
- Returns the length of the integer part of the bignum as
a num
- bignum.decLength()
- Returns the length of the decimal part of the bignum as
a num
- bignum.intPart()
- Returns the integer part of a bignum as a list
- bignum.decpart()
- Returns the decimal part of a bignum as a list
Output Functions:
These functions convert the bignum for output
- bignum.toString()
- This takes a bignum and outputs it into a human
readable format
- Returns a string with the value of the bignum
- bignum.toNum()
- Takes a bignum and returns a num
- This is limited by the range of BYOND’s num type
- bignum.debug()
- Takes a bignum and returns a string with debug info
- [sign] <[list of digits]> /
<[number of decimal places]><[length of the
bignum]>
--{[the number output in a string]}
#[ERROR code, if there is one else “”]#
Basic Math:
The
four main functions are defined in this library. They are all defined
under the bignum datum. None of the functions modify the input bignums;
they all return a third new bignum with the result. They all also have
a second argument (FLOAT) which is the number of digits to keep. Its
default is the world definition of precision (MAXFLOAT)
- bignum1. bigAdd(bignum2,FLOAT=MAXFLOAT)
- Adds bignum2 to bignum 1 and returns a third bignum.
- bignum1. bigSubtract(bignum2,FLOAT=
MAXFLOAT)
- Subtracts bignum2 from bignum 1 and returns a third
bignum.
- bignum1. bigMultiply(bignum2,FLOAT=
MAXFLOAT)
- Multiplies bignum2 by bignum 1 and returns a third bignum.
- bignum1. bigDivide(bignum2,FLOAT=
MAXFLOAT)
- Divides bignum1 by bignum 3 and returns a third bignum.
Secondary Functions:
There are two main secondary functions for bignum:
- bignum.bigCompare(value)
- This compares a bignum to a value
- The value can be in the following formats: bignum, num,
string
- This function can return: 1,0,-1
- 1 -> bignum is less than value (bignum
<value)
- 0 -> bignum is equal to value (bignum = value)
- -1 -> bignum is greater than value (bignum
> value)
- bignum.bigRound(n
decimal places)
- This will round a bignum to n decimal places
- For negative values of n, this rounds to the nearest 10^n
- For positive values of n, this rounds to the nearest
10^(n-1)
- n = 0 is the same as n = 1; it will round to the nearest 1
Composite Functions:
These are functions that use other primary or secondary
functions to perform a more complex function.
- bn_bigFactorial(n
as num)
- This takes a number and finds the factorial of that
number (n!)
- Note: this
is not defined under the bignum datum and will only take a standard
type number as an argument
- This returns a bignum with the factorial value
- For values over 500!, this function inserts a sleep()
statement to keep the program from freezing
Internal Functions:
These
are some internal functions that while not directly useful if you just
want to do basic math, are useful if you want to define your own
functions that modify bignums.
- Shifting Functions:
- bignum.shiftDigits(d
as num)
- This modifies a bignum but adding zeros to either side
while preserving the value of the bignum
- d can be positive or negative
- bignum.shiftDigits(4) ->
00001234.5678
- bignum.shiftDigits(-4) ->1234.56780000
- bignum.shiftDigitsDec(d
as num)
- This modifies a bignum by shifting the decimal place by
d places and adding zeros if needed
- d can be positive or negative
- bignum.shiftDigitsDec(4) -> 12345678
- bignum.shiftDigitsDec(-4) -> 0.12345678
- bn_shiftList(L
as list,d as num)
- This is a generalized proc that shifts a list (L) and
adds (d) zeros to either side
- A positive d adds zeros to the beginning of the list
- A negative d adds zeros to the end of the list
- list/L = list(8,7,6,5,4,3,2,1)
- bn_shiftList(L,4) ->
list(0,0,0,0,8,7,6,5,4,3,2,1)
- bn_shiftList(L,-4) ->
list(8,7,6,5,4,3,2,1,0,0,0,0)
- Cleanup:
- This trims any non-essential zeros from a number
- bignum = 000023232.2323000
- Bignum.trimZeros() -> 23232.2323
- This cleans str of all non-numerical characters
- It takes the first decimal place it finds and ignores
all others
- It returns a cleansed string
- List procs:
- Returns 1 if L is a list and 0 if it isn’t
- bn_list2text(list/L,
s as text)
- Takes a list L and returns a text string
- This takes into account the way bignum lists are stored
in reverse
- s is an optional character that is placed between digits
- bn_text2list(str
as text)
- Takes a text string and returns a list
- This takes into account the way bignum lists are stored
in reverse
- Additional procs:
- bignum.getDecimalPosition()
- This returns the position of the decimal point for
output/conversion to a string
- bignum.insertDecimal(str
as text)
- This adds a decimal point to the proper location within
str
- bignum.removeDecimal(str
as text)
- This takes str and returns a str with its decimal point
stripped out
- bn_getChar(str
as text,i as num)
- Returns the character at index i within a text string
- Creates and returns a bignum with value 0
Constants:
A few numbers are pre-defined within the bignum library. They
are defined under, bignum/CONST
- pi
- This returns a bignum of ? to n decimal points
- e – Euler’s constant
- This returns a bignum of e to n decimal points
- RAD – pi / 180 (radians to degrees)
- This returns a bignum of 180/ ? to n decimal points
- DAR – 180 / pi (degrees to radians)
- This returns a bignum of ?/180 to n decimal points