関数double2int マニュアル

(The documentation of function double2int)

Last Update: 2021/11/30

◆機能・用途(Purpose)

実数を指数部と仮数部の組合せに分解する。
Decompose a real number to a combination of exponent and mantissa parts.

この分解は
\[\begin{equation} d=A\times 10^B \label{eq.decomposition} \end{equation}\] と表される。ここで\(d\)は元々の実数、 \(A\)は仮数部(実数)、\(B\)は指数部(整数)である。仮数部は四捨五入して整数化する。この分解には任意性があるが、\(A\)の整数部分の桁数を指定することで一意な分解となる。
This decomposition is represented by eq. (\ref{eq.decomposition}), where \(d\) is the original real number, \(A\) is the mantissa part (a real number), and \(B\) is the exponent part (an integer). The mantissa part is rounded to an integer. Although this decomposition is not determined uniquely, the ambiguity is removed by specifying the number of digits of the integer part of \(A\).

◆形式(Format)

#include <doublemath.h>
inline int double2int (const double original,const int order,int ∗scale)

◆引数(Arguments)

original	分解前の実数。 The real number before the decomposition.
order	仮数部((\ref{eq.decomposition})式の\(A\))の整数部分の桁数。 The order (the number of digits) of the integer part of the mantissa (\(A\) in eq. \ref{eq.decomposition}\).
scale	分解後の指数部((\ref{eq.decomposition})式の\(B\))の代入先。 Memory into which the exponent part (\(B\) in eq. \ref{eq.decomposition}) is inserted during the function call.

◆戻り値(Return value)

分解後の仮数部((\ref{eq.decomposition})式の\(A\))を四捨五入した値。
The mantissa part of the decomposition (\(A\) in eq. \ref{eq.decomposition}), rounded to the nearest integer.

◆使用例(Example)

double original=12.345678;
int i;
int j=double2int(original,5,&i);
printf("original=%d∗10^%d\n",j,i);

この例では「12346∗10^-3」と表示される。第2引数が5なので仮数部を整数5桁として
\[\begin{equation} 12.345678=12345.678\times 10^{-3} \label{eq.example} \end{equation}\] と分解され、この12345.678を四捨五入して12346となる。
The output of this example is “12346∗10^-3”. Since the 2nd argument is 5, the original value is decomposed, using 5 digits for the integer part of the mantissa, as eq. (\ref{eq.example}), and then the mantissa of 12345.678 is rounded to 12346.

◆関数内部でのコーディングに関する説明 (A description for the internal coding of this function)

1. if(order<=0){ ...; }

引数orderが正でなければ (\ref{eq.decomposition})式のような分解はそもそも定義できないので order\(> 0\)になっているかチェックし、なっていない場合はエラー終了する。
Check that the argument “order” is positive, and if this requirement is not satisfied, the program finishes as an error. This is because the decomposition of eq. (\ref{eq.decomposition}) cannot be defined unless “order” is positive.

2. original_order=myfloor(log10(fabs(original)))+1;

originalの整数部分の桁数を求めるための計算で、 log10(|original|)+1の小数部を切り捨てた値を求めている。これは具体的に書き出してみると分かりやすい。例えば

\(100 \leq \)|original|\( < 1000\) のときoriginal_order\(=3\)
\( 10 \leq \)|original|\( < 100\) のときoriginal_order\(=2\)
\( 1 \leq \)|original|\( < 10\) のときoriginal_order\(=1\)
\( 0.1 \leq \)|original|\( < 1\) のときoriginal_order\(=0\)
\( 0.01 \leq \)|original|\( < 0.1\) のときoriginal_order\(=-1\)
\( 0.001 \leq \)|original|\( < 0.01\)のときoriginal_order\(=-2\)

である。
By this calculation, the number of digits of the integer part of “original” is obtained by dropping the decimal part of log10(|original|)+1. This calculation can be understood by writing down concrete values. For example,

original_order\(= 3\) for \(100 \leq \)|original|\( < 1000\);
original_order\(= 2\) for \( 10 \leq \)|original|\( < 100\);
original_order\(= 1\) for \( 1 \leq \)|original|\( < 10\);
original_order\(= 0\) for \( 0.1 \leq \)|original|\( < 1\);
original_order\(=-1\) for \( 0.01 \leq \)|original|\( < 0.1\); and
original_order\(=-2\) for \( 0.001 \leq \)|original|\( < 0.01\).

3. power=order-original_order;

「originalの整数部分の桁数をorder桁にするために originalを10の何乗倍しなければならないか」を表す整数値を求めている。
This computes an integer which represents the power of 10 to be multiplied with “original” to make the integer part having “order” digits.

4. magnified=original*pow(10.0,(double)(power));

originalを10^power倍した値を計算する。これによりmagnifiedの整数部分の桁数がちょうどorder桁となる。
Compute the value of “original” multiplied with 10^power. By this, the number of digits of the integer part of “magnified” is equal to “order”.

5. re=myround(magnified);

上で求めたmagnifiedを四捨五入する。得られる結果は求める仮数になっている。
Round the value of “magnified” obtained above, the result of which is the mantissa part needed.

6. ∗scale=-power;

powerを\(-1\)倍する。これは求める指数部になっている。
Multiply \(-1\) with “power”, the result of which is the exponent part needed.

7. return re;

仮数部を戻り値としてリターンする。
Return the mantissa part as the return value.

(\ref{eq.example})式の例での各ステップでの値の変遷を以下に示す。
Values of individual steps in case of eq. \(ref{eq.example}) are as follows.

関数実行前(Before the function)

original=12.345678
order=5
∗scale=不定値(undetermined)

関数内(In the function)

step2:
    original_order
         =myfloor(log10(fabs(12.345678)))+1
        =myfloor(log10(12.345678))+1
        =myfloor(1.091515)+1
        =1+1
        =2

step3:
    power=5-2=3

step4:
     magnified
         =12.345678∗pow(10.0,3.0)
        =12.345678∗1000.0
        =12345.678

step5:
    re=myround(12345.678)=12346

step6:
    ∗scale=-3

関数実行後(After the function)

j=12346
i=-3