Multi-Precision Arithmetic by C++ with no use of assembler
SN library Copyright (C) 1999-2018 K.Tsuru

Reference of class functions part 2

About error ID
To the functions Sign(int id ), etc. you can give to "id" an error ID number which identifies the place in the program. The ID numbers less than 10,000 are reserved in the library.


2. SNumber class's member functions
The prototype declarations are given in "snum.h". This class is derived from SNManager class by "public virtual".
It defines the common parts of real number and integer, i.e. an integer array which holds the figures of multi-precision number and sign.
"SNBlock" type used below is defined as

typedef NCBlock<FType> SNBlock;

where "NCBlock" is a class template defined in "ncblock.h". "SNBlock" is the type of "FType"(unsigned short) array "figure[]" which is a "private" member of this class and holds the figures of multi-precision number.

enumerating constants
function It gives the definition of values for sign.
form enum SNumber::{ MINUS = -1, ZERO = 0, PLUS = 1, UNDECIDED = 0x10 };
comment UNDECIDED : "figure[]" is not initialized or empty

SetSNBlock, SetSNBlockNorm
function It sets a number by a "SNBlock" object and a sign "sgn".
form
void SNumber::SetSNBlock(const SNBlock& a, int sgn); does not normalization
void SNumber::SetSNBlockNorm(const SNBlock& a, int sgn); including Normalize()

FigureAlloc
function "x.FigureAlloc(size, copy)" allocates memory of "x.figure[]".
form void SNumber::FigureAlloc(uint size, int copy);
comment It does not free memory. Use "SizeZero()" for free memory.
It decides the sign shown in the parentheses below.
"copy=0": All elements are initialized by zero(ZERO).
"copy>0": It copies lower elements and upper part is initialized by zero(MINUS/ZERO/PLUS).
"copy<0": It allocates memory only and do not initialize by zero(UNDECIDED).
It returns actually allocated size of "figure[]" which is the power of 2.

SetZero
function It sets all elements of "figure[]" and sign zero. In the reducible size mode it reduces the size to "minArraySize"(=4).
form virtual void SNumber::SetZero();

SizeZero
function "x.SizeZero()" frees the memory of "x.figure[]" and sets sign "UNDECIDED".
form inline void SNumber::SizeZero();

Head, Tail
function It returns the position of non-zero elements in "figure[]".
form
uint SNumber::Head() const;
uint SNumber::Tail() const;
comments In the case of an integer 'a'
a = f[0]+f[1]*R+f[2]*R 2+...+f[h]*R h (R : radix)
a.figure[] =(f[0],...f[t],...f[h],....f[s-1])
f[i] = 0 for i = 0,1,2, ...t-1, f[t] !=0, ..., f[h] !=0, f[j] = 0 for j =h+1,...,s-1,
"a.Tail()" returns 't' and "a.Head()" returns 'h'. The size 's' is taken a power of 2.

ReadFigures
function It provides a method to read the elements of "figure[]" via pointer, faster than "operator()".
form const FType* SNumber::ReadFigures() const:
usage
 const FType* mv = m.ReadFigures();
.... mv[] can be used as rhs/not lhs......
reference "Effective C++ by S. Meyers"

FigureSize
function It returns the size of "figure[]" i.e. "figure.size()".
form uint SNumber::FigureSize() const;

Sign, RawSign
"x.Sign()" returns the sign of "x" by enumerating constants above. If "x" has not been initialized yet an error occurs, i.e. when "sign == UNDECIDED", the program abnormally terminates. "x.RawSign()" does not cause this error.
form
virtual int SNumber::Sign(int id = 11) const;
int SNumber::RawSign() const;
comment All classes derived from "SNumber" can call this function.

operator()
function "m(n)" returns n-th element of "m.figure[]".
form FType SNumber::operator()(int n) const;
comment For the value "n<0" or "n>=figure.size()" it returns zero. It can be used as rhs (read only). Do not use in a large "for" loop, because of much overhead time.

operator[]
function "m[n]" returns n-th element of "m.figure[]".
form FType SNumber::operator[](int n) const;
comment It returns a raw value without checking the range of 'n' and size of "figure[]". Use when you are sure that "0 <= n < figure.size()". It can not be used as lhs. For writing into "figure[]" please use "SetSNBlock()" function.

Example
SLong a;
//a[0]=1; /* error */
if(a(0) & 1){ //if(a[0] & 1) is also Ok.
/*a is odd number*/
}else{
/*a is even mumber*/
}

ChangeSign
function "m.ChangeSign();" changes the sign of multi-precision object m.
form void SNumber::ChangeSign(int id = 13);
comment This is faster than a statement "m = -m;" which calls copying routine.

MaxSize
function "m.MaxSize()" returns the maximum size of figures which depends on the radix of object and the significant figures set by "SetEffFig()" for the real number.
form uint MaxSize() const;
comment For the real number it returns the sum of maximum significant figures and some hidden figures which are introduced to keep the precision good. For the integer it returns the upper limit of figures( 4,194,304/DFIGURES(=4) in decimal radix).
The binary radix object returns the value of decimal radix object multiplied by log10(DRADIX/BRADIX).


3. RealSize class's member functions
The prototype declarations are given in "sreal.h". This class is derived from SNManager class by "public virtual".

enumerating constants

form enum RealSize::{ PROPER = 1, TEMP_EXTEND = 2, PREF_SPEED = 4};
comment : If "PROPER" bit is ON, set an efficient size for memory and FFT. "TEMP_EXTEND" bit should be ON when you temporally extend significant figures. If "PREF_SPEED" bit is ON, set SNManager::preferSpeed = ON.

constructors
form
RealSize(); default constructor
RealSize(uint ef, int p = 0);
comment Give 'ef' the number of significant figures in decimal radix (DRADIX) which you want, 'p'  an integer using enumerating constants above. If "TEMP_EXTEND" bit is ON, 'ef  ' can exceed the upper limit of significant figures without warning and it is automatically adjusted to the maximum value.  

SetEffFig
function
It provides a method to change the number of significant figures.
form uint RealSize::SetEffFig(uint eff, int p = 0);
comment About the meaning of arguments see the comment of the above second constructor.

4. SCalcInfo structure's members and member functions
The prototype declarations are given in "sreal.h". This structure treats the information of series and iteration. All members are public.
definition
struct SCalcInfo {
 static int iterationCount; // number of iteration in Newton method, etc.
 static ulong upToTerm; // number of summing up terms in series

 int ItrCounts() const {
 int it = iterationCount;
 iterationCount = 0; // reset
 return it;
 }
 ulong UpToTerm() const {
 ulong ut = upToTerm;
 upToTerm = 0; // reset
 return ut;
 }
};

comment SDouble class is derived form this class by "public virtual". Then its object can access the members above such as

SDouble a;
......
a.iterationCount = k;