==================================
ユーティリティ関数
==================================

以下のユーティリティ関数を使うことができます。

.. hint::

   * 以下の説明において、引数・返り値が (double value, int digit) -> double と説明されているとき、

     * 引数はdouble型, int型の2つということを表します
     * 引数名value, digitは説明のためであり、モデリング上は特に関係ありません
     * 返り値はdouble型ということを表します

   * 引数・返り値が複数ある場合は、算式の中の引数の数や型に応じて適切なものが選ばれます。


Utl.round
    :引数・返り値1: (double value) -> double
    :引数・返り値2: (double value, int digit) -> double
    :説明: | 四捨五入を行い、小数点以下digit桁に丸めます。
           | digitを指定しなかった場合は整数となるように丸めます。
           | digitが負の場合はエラーとなります。

Utl.log
    :引数・返り値: (double value) -> double
    :説明: 対数を計算します

Utl.exp
    :引数・返り値: (double value) -> double
    :説明: 指数を計算します

Utl.abs
    :引数・返り値1: (int value) -> int
    :引数・返り値2: (double value) -> double
    :説明: 絶対値を計算します


Utl.max
    :引数・返り値1: (int a, int b) -> int
    :引数・返り値2: (double a, double b) -> double
    :引数・返り値3: (int a, int b, int c) -> int
    :引数・返り値4: (double a, double b, double c) -> double
    :説明: 最大値を計算します

Utl.min
    :引数・返り値1: (int a, int b) -> int
    :引数・返り値2: (double a, double b) -> double
    :引数・返り値3: (int a, int b, int c) -> int
    :引数・返り値4: (double a, double b, double c) -> double
    :説明: 最小値を計算します

Utl.clip
    :引数・返り値1: (double a, double mn, double mx) -> double
    :引数・返り値2: (int a, int mn, int mx) -> int
    :説明: | aがmn以下であればmn、aがmx以上であればmx, そうでなければaを返します
           | mn > mx となっている場合はエラーとなります
Utl.sum
    :引数・返り値: (double[] ary) -> double
    :説明: 配列の和を返します

Utl.sum_range
    :引数・返り値: (double[] ary, int start, int last) -> double
    :説明: | 配列のstart番目からlast番目までの和を返します。
           | start, lastがaryの範囲を超えている場合、範囲の最初の値、最後の値となります
           | start > last となっている場合は、0を返します

Utl.average
    :引数・返り値: (double[] ary) -> double
    :説明: 配列の平均値を返します。

Utl.average_range
    :引数・返り値: (double[] ary, int start, int last) -> double
    :説明: | 配列のstart番目からlast番目までの平均値を返します。
           | start, lastがaryの範囲を超えている場合、範囲の最初の値、最後の値となります
           | start > last となっている場合は、0を返します

Utl.sum_product
    :引数・返り値: (double[] ary1, double[] ary2) -> double
    :説明: | 配列の対応する要素の積を計算し、その和を返します
           | ary1, ary2の要素数が異なる場合はエラーとなります

Utl.sum_product_range
    :引数・返り値: (double[] ary1, double[] ary2, int start, int last) -> double
    :説明: | 配列のstart番目からlast番目までの対応する要素の積を計算し、その和を返します
           | ary1, ary2の要素数が異なる場合はエラーとなります
           | start, lastが配列の範囲を超えている場合、範囲の最初の値、最後の値となります
           | start > last となっている場合は、0を返します

Utl.normsdist
    :引数・返り値: (double z) -> double
    :説明: 標準正規分布の累積分布関数の値を返します

Utl.normsinv
    :引数・返り値: (double p) -> double
    :説明: 標準正規分布の累積分布関数の逆関数の値を返します

Util.irr
    :引数・返り値: (double[] ary) -> double
    :説明: | 内部収益率を計算します
           | 各要素が年ごとの値であることが想定されています
           | 計算時間が比較的長い計算です。特に配列の要素数が多い場合に計算時間がかかるため、要素数を200以下とすることを推奨します。
           | 内部収益率が計算できない場合、配列の和が正のときには100.0、そうでない場合は-100.0を返します。


Utl.to_annual
    :引数・返り値1: (double[] ary, int yearsLast) -> double[]
    :引数・返り値2: (double[] ary, int yearsLast, int[] years) -> double[]
    :説明: | 月単位の配列を年単位の配列に直すための関数です
           | yearsLastは直した後の配列の最後の要素のインデックスです
           | yearsがない場合、配列aryの0番目の要素は0番目、1-12番目は1番目, 13-24は2番目.. にマッピングされ、和が計算されます
           | yearsがある場合、配列aryの要素は配列yearの対応する要素のインデックスにマッピングされ、和が計算されます
           | ary, yearsの要素数が異なる場合はエラーとなります

    :説明 - ロジック (引数・返り値1): 返り値の配列のi番目の要素の値は以下で表されます
             ::

                ret = 0.0
                for (k = 0; k < ary.Length; k++)
                    if(k >= (i-1) * 12 + 1 && k <= (i * 12))
                        ret += ary[k]

    :説明 - ロジック (引数・返り値2): 返り値の配列のi番目の要素の値は以下で表されます
             ::

                ret = 0.0
                for (k = 0; k < ary.Length; k++)
                    if(i == years[k])
                        ret += ary[k]

Utl.pv
    :引数・返り値: (double[] cf, double[] disc, double[] cfDisc) -> double[]
    :説明: | 各期末における翌期以降のCFの現価を計算します
           | cf, disc, cfDiscの要素数が異なる場合はエラーとなります

    :説明 - ロジック: 返り値の配列のi番目の要素の値は以下で表されます
             ::

                ret = 0.0
                (for k = i + 1; k < cf.Length; k++)
                   ret += cf(k) * cfDisc(k) / disc(i)