1math::bignum(n)                Tcl Math Library                math::bignum(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       math::bignum - Arbitrary precision integer numbers
9

SYNOPSIS

11       package require Tcl  ?8.4?
12
13       package require math::bignum  ?3.1?
14
15       ::math::bignum::fromstr string ?radix?
16
17       ::math::bignum::tostr bignum ?radix?
18
19       ::math::bignum::sign bignum
20
21       ::math::bignum::abs bignum
22
23       ::math::bignum::cmp a b
24
25       ::math::bignum::iszero bignum
26
27       ::math::bignum::lt a b
28
29       ::math::bignum::le a b
30
31       ::math::bignum::gt a b
32
33       ::math::bignum::ge a b
34
35       ::math::bignum::eq a b
36
37       ::math::bignum::ne a b
38
39       ::math::bignum::isodd bignum
40
41       ::math::bignum::iseven bignum
42
43       ::math::bignum::add a b
44
45       ::math::bignum::sub a b
46
47       ::math::bignum::mul a b
48
49       ::math::bignum::divqr a b
50
51       ::math::bignum::div a b
52
53       ::math::bignum::rem a b
54
55       ::math::bignum::mod n m
56
57       ::math::bignum::pow base exp
58
59       ::math::bignum::powm base exp m
60
61       ::math::bignum::sqrt bignum
62
63       ::math::bignum::rand bits
64
65       ::math::bignum::lshift bignum bits
66
67       ::math::bignum::rshift bignum bits
68
69       ::math::bignum::bitand a b
70
71       ::math::bignum::bitor a b
72
73       ::math::bignum::bitxor a b
74
75       ::math::bignum::setbit bignumVar bit
76
77       ::math::bignum::clearbit bignumVar bit
78
79       ::math::bignum::testbit bignum bit
80
81       ::math::bignum::bits bignum
82
83______________________________________________________________________________
84

DESCRIPTION

86       The  bignum  package  provides  arbitrary  precision integer math (also
87       known as "big numbers") capabilities to the Tcl language.  Big  numbers
88       are internally represented at Tcl lists: this package provides a set of
89       procedures operating against the internal representation in order to:
90
91       ·      perform math operations
92
93       ·      convert bignums from the internal representation to a string  in
94              the desired radix and vice versa.
95
96       But  the  two  constants "0" and "1" are automatically converted to the
97       internal representation, in order to easily compare a number  to  zero,
98       or increment a big number.
99
100       The  bignum  interface is opaque, so operations on bignums that are not
101       returned by procedures in this package (but created by hand)  may  lead
102       to  unspecified behaviours.  It's safe to treat bignums as pure values,
103       so there is no need to free a bignum, or to duplicate it via a  special
104       operation.
105

EXAMPLES

107       This  section  shows some simple example. This library being just a way
108       to perform math operations, examples may be the simplest way  to  learn
109       how  to  work  with  it.  Consult  the API section of this man page for
110       information about individual procedures.
111
112                  package require math::bignum
113
114                  # Multiplication of two bignums
115                  set a [::math::bignum::fromstr 88888881111111]
116                  set b [::math::bignum::fromstr 22222220000000]
117                  set c [::math::bignum::mul $a $b]
118                  puts [::math::bignum::tostr $c] ; # => will output 1975308271604953086420000000
119                  set c [::math::bignum::sqrt $c]
120                  puts [::math::bignum::tostr $c] ; # => will output 44444440277777
121
122                  # From/To string conversion in different radix
123                  set a [::math::bignum::fromstr 1100010101010111001001111010111 2]
124                  puts [::math::bignum::tostr $a 16] ; # => will output 62ab93d7
125
126                  # Factorial example
127                  proc fact n {
128                      # fromstr is not needed for 0 and 1
129                      set z 1
130                      for {set i 2} {$i <= $n} {incr i} {
131                          set z [::math::bignum::mul $z [::math::bignum::fromstr $i]]
132                      }
133                      return $z
134                  }
135
136                  puts [::math::bignum::tostr [fact 100]]
137
138

API

140       ::math::bignum::fromstr string ?radix?
141              Convert string into a bignum. If radix is omitted or  zero,  the
142              string  is  interpreted  in hex if prefixed with 0x, in octal if
143              prefixed with ox, in binary if it's pefixed with bx, as a number
144              in  radix  10 otherwise. If instead the radix argument is speci‐
145              fied in the range 2-36, the string is interpreted in  the  given
146              radix.  Please  note  that this conversion is not needed for two
147              constants : 0 and 1. (see the example)
148
149       ::math::bignum::tostr bignum ?radix?
150              Convert bignum into a string  representing  the  number  in  the
151              specified radix. If radix is omitted, the default is 10.
152
153       ::math::bignum::sign bignum
154              Return  the  sign of the bignum.  The procedure returns 0 if the
155              number is positive, 1 if it's negative.
156
157       ::math::bignum::abs bignum
158              Return the absolute value of the bignum.
159
160       ::math::bignum::cmp a b
161              Compare the two bignums a and b, returning 0 if a == b, 1 if a >
162              b, and -1 if a < b.
163
164       ::math::bignum::iszero bignum
165              Return  true  if  bignum  value  is  zero,  otherwise  false  is
166              returned.
167
168       ::math::bignum::lt a b
169              Return true if a < b, otherwise false is returned.
170
171       ::math::bignum::le a b
172              Return true if a <= b, otherwise false is returned.
173
174       ::math::bignum::gt a b
175              Return true if a > b, otherwise false is returned.
176
177       ::math::bignum::ge a b
178              Return true if a >= b, otherwise false is returned.
179
180       ::math::bignum::eq a b
181              Return true if a == b, otherwise false is returned.
182
183       ::math::bignum::ne a b
184              Return true if a != b, otherwise false is returned.
185
186       ::math::bignum::isodd bignum
187              Return true if bignum is odd.
188
189       ::math::bignum::iseven bignum
190              Return true if bignum is even.
191
192       ::math::bignum::add a b
193              Return the sum of the two bignums a and b.
194
195       ::math::bignum::sub a b
196              Return the difference of the two bignums a and b.
197
198       ::math::bignum::mul a b
199              Return the product of the two bignums a and b.  The  implementa‐
200              tion  uses Karatsuba multiplication if both the numbers are big‐
201              ger than a given threshold, otherwise  the  direct  algorith  is
202              used.
203
204       ::math::bignum::divqr a b
205              Return  a two-elements list containing as first element the quo‐
206              tient of the division between the two bignums a and b,  and  the
207              remainder of the division as second element.
208
209       ::math::bignum::div a b
210              Return  the  quotient  of the division between the two bignums a
211              and b.
212
213       ::math::bignum::rem a b
214              Return the remainder of the division between the two  bignums  a
215              and b.
216
217       ::math::bignum::mod n m
218              Return n modulo m. This operation is called modular reduction.
219
220       ::math::bignum::pow base exp
221              Return base raised to the exponent exp.
222
223       ::math::bignum::powm base exp m
224              Return  base raised to the exponent exp, modulo m. This function
225              is often used in the field of cryptography.
226
227       ::math::bignum::sqrt bignum
228              Return the integer part of the square root of bignum
229
230       ::math::bignum::rand bits
231              Return a random number of at most bits bits.  The returned  num‐
232              ber is internally generated using Tcl's expr rand() function and
233              is not  suitable  where  an  unguessable  and  cryptographically
234              secure random number is needed.
235
236       ::math::bignum::lshift bignum bits
237              Return  the  result of left shifting bignum's binary representa‐
238              tion of bits positions on the left.  This is equivalent to  mul‐
239              tiplying by 2^bits but much faster.
240
241       ::math::bignum::rshift bignum bits
242              Return  the result of right shifting bignum's binary representa‐
243              tion of bits positions on the  right.   This  is  equivalent  to
244              dividing by 2^bits but much faster.
245
246       ::math::bignum::bitand a b
247              Return  the  result of doing a bitwise AND operation on a and b.
248              The operation is restricted to positive numbers, including zero.
249              When  negative  numbers  are provided as arguments the result is
250              undefined.
251
252       ::math::bignum::bitor a b
253              Return the result of doing a bitwise OR operation on  a  and  b.
254              The operation is restricted to positive numbers, including zero.
255              When negative numbers are provided as arguments  the  result  is
256              undefined.
257
258       ::math::bignum::bitxor a b
259              Return  the  result of doing a bitwise XOR operation on a and b.
260              The operation is restricted to positive numbers, including zero.
261              When  negative  numbers  are provided as arguments the result is
262              undefined.
263
264       ::math::bignum::setbit bignumVar bit
265              Set the bit at bit position to 1 in the  bignum  stored  in  the
266              variable bignumVar. Bit 0 is the least significant.
267
268       ::math::bignum::clearbit bignumVar bit
269              Set  the  bit  at  bit position to 0 in the bignum stored in the
270              variable bignumVar. Bit 0 is the least significant.
271
272       ::math::bignum::testbit bignum bit
273              Return true if the bit at the bit position of bignum is on, oth‐
274              erwise  false is returned. If bit is out of range, it is consid‐
275              ered as set to zero.
276
277       ::math::bignum::bits bignum
278              Return the number of bits needed to represent bignum in radix 2.
279

BUGS, IDEAS, FEEDBACK

281       This document, and the package it describes, will  undoubtedly  contain
282       bugs  and  other  problems.  Please report such in the category math ::
283       bignum of the Tcllib  Trackers  [http://core.tcl.tk/tcllib/reportlist].
284       Please  also  report any ideas for enhancements you may have for either
285       package and/or documentation.
286
287       When proposing code changes, please provide unified diffs, i.e the out‐
288       put of diff -u.
289
290       Note  further  that  attachments  are  strongly  preferred over inlined
291       patches. Attachments can be made by going  to  the  Edit  form  of  the
292       ticket  immediately  after  its  creation, and then using the left-most
293       button in the secondary navigation bar.
294

KEYWORDS

296       bignums, math, multiprecision, tcl
297

CATEGORY

299       Mathematics
300
302       Copyright (c) 2004 Salvatore Sanfilippo <antirez at invece dot org>
303       Copyright (c) 2004 Arjen Markus <arjenmarkus at users dot sourceforge dot net>
304
305
306
307
308tcllib                                3.1                      math::bignum(n)
Impressum