Technical support e-mail : mktmk<at>narod.ru.

Home page                : http://mktmk.narod.ru.

 

Multiprecision unsigned number template library (MUNTL)

Distributed under the GNU LGPL.

 

Users guide.

 

0. Version list

 

v1.01 - adapt for GCC 3.2.2.

v1.00 - project start.

 

1. The purpose of program.

 

The program (library) is intended for the organization of calculations with the big

precision for unsigned numbers. For use this program only one header file di.h (25Kb) is necessary. The program works very quickly. As against other similar programs this program does not use the heap call (new, malloc etc.). All buffers for storage of numbers are allocated at compile-time. The program does not use GMP and other libraries for work with long numbers. The program use only pure C++ code.

 

 

2. Conditions of application.

 

The program is written on "pure" C++ with template. The program does not

use the assembler. The program is tested by BCB60 in ANSI-compatibility mode.

The program is tested by GCC 3.2.2.

Configuration of test computer: Athlon 1800, Chaintech 7AJA2, 256Mb RAM.

Test time (file dit.cpp) is 42 second.

 

3. The problem description.

 

Sometimes it is necessary to have unsigned numbers which length exceeds

ability of a current platform. For example:

 

 - Storage of the big numbers (for example factorials) and operations with them.

 - Emulation of registers of the big length.

 - Indication of many error in position code.

 

This program is intended for the decision of these problems.

 

4. The input and output data.

 

4.1 General description.

 

Numbers of the big precision are realized as template class di_unsigned.

This template class have the overloaded arithmetic operations. Due to this,

di_unsigned may use as usual unsigned numbers.

 

Word length of numbers di_unsigned do not limited.

 

Inside a class di_unsigned the information is stored as array.

 

4.2 Structure of the project.

 

File  di.h           - is template library.

Files dit.cpp, dit.h - is the test of template library.

File  die.cpp        - is an example of use template library.

File  readrus.txt    - is this users guide in Russian.

File  readeng.txt    - is this users guide in English.

 

4.3 Parameters of template.

 

The template di_unsigned have 3 parameters.

 

template <class T,class Tunit,T size> class di_unsigned;

 

The first parameter  "T"     - is type of the counter of bits.

The second parameter "Tunit" - is type of internal array which stored the

                               information.

The third parameter  "size"  - is numerical parameter. Determines length

                               di_unsigned in bits.

 

Type "T" should may contain number "size". For example if "T" is unsigned char,

parameter "size" can not be more than 255.

 

Type "Tunit" should be unsigned for correct work of right shifts operator.

 

For increase of performance it is recommended to choose "Tunit" equal to

machine word for the current platform. For win32 it is recommended use

"unsigned int" as "Tunit".

 

Unsigned char and char of the current platform should be one size for correct

work functions "printtostring".

 

Unsigned char and char of the current platform should have even number of bits.

Problems are possible on the platforms having CHAR_BIT=7.

 

Is possible use of di_unsigned with different parameter "size" in one

arithmetic expression (see example in a file die.cpp).

 

This version not supported use of numbers with different types "T" or "Tunit"

in one arithmetic expression.

 

Type "T" should may contain size+size1 for correct work of operation of

multiplication. (Size and size1 is parameter "size" of two di_unsigned operand

in binary operator).

 

Type "T" should may contain size+1 and size1+1 for correct work of operation of

division.

 

4.4 Example of use di_unsigned.

 

// Inclusion of library of templates di_unsigned

#include <di.h>

// Inclusion of library of standard input-output

#include <stdio.h>

 

// Word length of the first type

const unsigned int numberbit1=250;

 

// Word length of the second type

const unsigned int numberbit2=253;

 

// Definition of the first type

typedef di_unsigned < unsigned int, unsigned int, numberbit1 > big_digit1;

 

// Definition of the second type

typedef di_unsigned < unsigned int, unsigned int, numberbit2 > big_digit2;

 

// Use "unsigned int" as T and Tunit 

 

int main (int argc, char* argv []) {

 

// Length of a text string for print first number

const unsigned int l1 = ((numberbit1)/CHAR_BIT+1)*2+1;

 

// Length of a text string for print second number

const unsigned int l2 = ((numberbit2)/CHAR_BIT+1)*2+1;

 

// Text string for print first number

char string1 [l1];

 

// Text string for print second number

char string2 [l2];

 

// Initialization of three numbers

big_digit1 d1=1;

big_digit2 d2=1;

big_digit2 d3;

 

// left shift operator 

d1 <<= (numberbit1/2+1);

d2 <<= numberbit1/2;

 

// increment operator

++d1;

 

// print of result

d1.printtostring (string1, l2);

d2.printtostring (string2, l2);

 

printf (" \nd1   =0x%s ", string1);

printf (" \nd2   =0x%s ", string2);

 

// addition operator

d3=d1+d2;

 

// print of result

d3.printtostring (string2, l2);

printf ("\nd1+d2=0x%s", string2);

 

// multiplication operator

d3=d1*d2;

 

// print of result

d3.printtostring (string2, l2);

printf ("\nd1*d2=0x%s", string2);

 

// division operator 

d3=d1/d2;

 

// print of result

d3.printtostring (string2, l2);

printf ("\nd1/d2=0x%s", string2);

 

// modulus operator

d3=d1%d2;

 

// print of result

d3.printtostring (string2, l2);

printf ("\nd1%sd2 =0x%s", "", string2);

 

return 0;

}

 

4.5 The description of functions - members.

 

For a template di_unsigned the following operators are determined:

 

&  - bitwise AND

&= - bitwise AND with assignment

|  - bitwise inclusive OR

|= - bitwise inclusive OR with assignment

^  - bitwise exclusive OR

^= - bitwise exclusive OR with assignment

~  - bitwise complement

 

=  - assignment

 

== - equality                     

!= - inequality

>  - greater than

<  - less than

>= - greater than or equal

<= - less than or equal

 

<<  - left shift

<<= - left shift with assignment

>>  - right shift

>>= - right shift with assignment

 

+  - addition

+= - addition with assignment

-  - subtraction

-= - subtraction with assignment

++ - preincrement and postincrement

-- - predecrement and postdecrement

 

*  - multiplication

*= - multiplication with assignment

/  - division

/= - division with assignment

%  - modulus operator

%= - modulus operator with assignment

 

Additional functions:

 

void clear(); - set "all zero"

void set();   - set "all one"

 

void clear(const T bit); - clear a bit with specified number

void set(const T bit);   - set   a bit with specified number

 

bool tst(const T bit) const; - check a bit with specified number. Return

                                true, if bit is 1 and false in opposite case.

 

const T getbite() const;     - returns precision of number (parameter "size" of

                               template)

 

bool getcf() const;          - returns a status of carry. It is established

                               after operations of addition and subtraction.

 

di_version ver() const;          - returns version of library

di_serialnumber sernum() const;  - returns serial number of library

 

operator const Tunit * () const; - cast to pointer of Tunit. (Return internal

                                   array. Do not modify it.)

 

void printtostring (char* c_str, T lengthstr); - prints the number to c_str

                                                 in hex format .

 

di_unsigned(); - constructor without parameters. It do not clear internal array.

 

di_unsigned (const di_unsigned& d); - constructor

 

template <T size1>

di_unsigned (const di_unsigned <T,Tunit,size1>& d); - constructor

 

template < class Tv >

di_unsigned (const Tv& val); - constructor. "Tv" should be unsigned.

                               For example unsigned int, unsigned long int.

 

di_unsigned(const char* c_str); - constructor. The line c_str should contain

                                  hex string with zero at end. Any invalid

                                  symbol finishes convertion.

 

Operators of assignment. Parameters - as in the appropriate constructors.

 

di_unsigned& operator = (const di_unsigned& d);

 

template <T size1>

di_unsigned& operator = (const di_unsigned <T,Tunit,size1>& d);

 

template < class Tv >

di_unsigned& operator = (const Tv& val);

 

di_unsigned& operator = (const char* c_str);

 

4.6 Use of functions - members.

 

The binary addition operator "+" returns number with the greater length from

two operands. For example, at addition of numbers of 100 and 200 bits this

operator will return result with length of 200 bits.

 

The binary multiplication operator "*" returns number with the length equal

to the sum of lengths two operands. For example, at multiplication of numbers

of 100 and 200 bits this operator will return result with length of 300 bits.

 

The binary division operator "/" returns number with the length equal to

length divided.

 

The binary modulus operator "%" returns number with length equal length of

divider.

 

If user define DI_EXCEPTIONENABLE macro, the library will throw exception if

division by zero will occur.

 

class di_exception {

public:

di_exception(){}

};

 

By default DI_EXCEPTIONENABLE do not define.

 

Any operators and functions have not check correct of their parameters.

For example, if to apply function set(200) to number with length of 100 bits,

will take crash of programs.