6.16. kink/NUM¶
6.16.1. num型¶
numは十進の浮動小数点数である。num値は次の属性から構成される:
• Mantissa: 数値から小数点を取り除いて得られる符号付き整数
• Scale: 小数部の桁の個数である非負の整数
num値は、 `Mantissa * (10 ** (-Scale))` という数値を表現する。無限大、NaN, 符号付きゼロはサポートされない。
不変条件
Mantissaについて、次の不変条件が成り立つ:
• mantissa_bits = 8192
• max_mantissa = 2**mantissa_bits - 1
• min_mantissa = - (2**mantissa_bits - 1)
• min_mantissa ≦ Mantissa ≦ max_mantissa
Scaleについては:
• max_scale = 32767
• 0 ≦ Scale ≦ max_scale
この範囲で、num値は次の値を表現できる:
• すべてのinstant値のエポック秒を、ナノ秒の精度で。
• 有限の（NaNや±Infinityでない）IEEE 754 binary64またはdecimal128値。ただし、ゼロの符号を除く。
同値性
ひとつの数値について複数の表現があり得る。たとえば、420は (Mantissa=420, Scale=0), (Mantissa=42000, Scale=2) などのように表現される。これらの値は、==演算子（op_eqメソッド）で同値として扱われる:
stdout.print_line((420 == 420.00).repr) # => true
ビット操作
ビット操作は整数のnum値だけをオペランドとして取る。非負のnum値は、0のビットが無限に先行しているように扱われる。負のnum値は、1のビットが無限に先行する、2の補数表現として扱われる。
stdout.print_line((~ 0b_1010).repr) # => (-11)
stdout.print_line('{%b}'.format(~ 0b_1010)) # => -1011
stdout.print_line('{%b}'.format(~ 0b_1010 & 0b_1111_1111)) # => 11110101
6.16.1.1. Num.mantissa¶
mantissaはNumのMantissaを戻す。
結果は整数のnum値である。
例
stdout.print_line(123.45.mantissa.repr) # => 12345
6.16.1.2. Num.scale¶
scaleはNumのScaleを戻す。
結果は整数のnum値である。
例
stdout.print_line(123.45.scale.repr) # => 2
6.16.1.3. Num.int?¶
int?はNumが整数かどうかを戻す。
num値が整数であるのは、Scaleが0であるときである。
例
stdout.print_line(120.int?.repr) # => true
stdout.print_line(120.0.int?.repr) # => false
stdout.print_line(3.14.int?.repr) # => false
6.16.1.4. X + Y¶
+演算子、つまりop_addメソッドは、XとYの和を戻す。
結果のScaleはmax(X.scale, Y.scale)である。
事前条件
Yはnum値でなければならない。
例
:Sum <- 1.234 + 0.12
stdout.print_line(Sum.repr) # => 1.354
stdout.print_line(Sum.scale.repr) # => 3
6.16.1.5. X - Y¶
二項の - 演算子、つまりop_subメソッドは、XとYの差を戻す。
結果のScaleはmax(X.scale, Y.scale)である。
事前条件
Yはnum値でなければならない。
例
:Diff <- 1.234 - 0.12
stdout.print_line(Diff.repr) # => 1.114
stdout.print_line(Diff.scale.repr) # => 3
6.16.1.6. - X¶
単項の - 演算子、つまりop_minusメソッドは、Xの符号を反転する。
例
stdout.print_line((-42).repr) # => (-42)
stdout.print_line((-(-42)).repr) # => 42
stdout.print_line((-0).repr) # => 0
6.16.1.7. X * Y¶
* 演算子、つまりop_mulメソッドは、XとYの積を戻す。
結果のScaleは X.scale + Y.scale である。
事前条件
Yはnum値でなければならない。
例
:Prod <- 1.2 * 3.45
stdout.print_line(Prod.repr) # => 4.140
stdout.print_line(Prod.scale.repr) # => 3
6.16.1.8. X / Y¶
/ 演算子、つまりop_divメソッドは、(Dividend=X, Divisor=Y)からなるnum_div値を戻す。
num_div値からどのように値を取り出すかについては、kink/NUM_DIVを見よう。
事前条件
Yはnum値でなければならない。
Yは0と等しくてはならない。
例
stdout.print_line((10 / 3).floor(3).repr) # => 3.333
stdout.print_line((10 / 3).ceil(3).repr) # => 3.334
6.16.1.9. X // Y¶
//演算子、つまりop_intdivメソッドは、整数除算をおこなって、商を戻す。
Q = X // Y と R = X % Y は、次の条件を満たす。
• Q * Y + R = X
• 0 ≦ R < Y.abs
• Q.scale = 0
• R.scale = max(X.scale Y.scale)
事前条件
Yはnum値でなければならない。
Yは0と等しくてはならない。
例
:attempt_intdiv <- {(:X :Y)
:Q = X // Y
:R = X % Y
stdout.print_line('{} // {} = {}, remainder: {}'.format(X.repr Y.repr Q.repr R.repr))
}
attempt_intdiv(10 3)
# => 10 // 3 = 3, remainder: 1
attempt_intdiv(10 (-3))
# => 10 // (-3) = (-3), remainder: 1
attempt_intdiv((-10) 3)
# => (-10) // 3 = (-4), remainder: 2
attempt_intdiv((-10) (-3))
# => (-10) // (-3) = 4, remainder: 2
attempt_intdiv(10 1.5)
# => 10 // 1.5 = 6, remainder: 1.0
attempt_intdiv(5.5 3)
# => 5.5 // 3 = 1, remainder: 2.5
attempt_intdiv(5.5 1.5)
# => 5.5 // 1.5 = 3, remainder: 1.0
6.16.1.10. X % Y¶
% 演算子、つまりop_remメソッドは、整数除算をおこなって、剰余を戻す。
詳細は X // Y を見よう。
事前条件
Yはnum値でなければならない。
Yは0と等しくてはならない。
6.16.1.11. X | Y¶
| 演算子、つまりop_orメソッドは、XとYに対してビットOR演算をおこなう。
結果は整数のnum値である。
事前条件
Xは整数のnum値でなければならない。
Yは整数のnum値でなければならない。
6.16.1.12. X ^ Y¶
^ 演算子、つまりop_xorメソッドは、XとYに対してビットXOR演算をおこなう。
結果は整数のnum値である。
事前条件
Xは整数のnum値でなければならない。
Yは整数のnum値でなければならない。
6.16.1.13. X & Y¶
& 演算子、つまりop_andメソッドは、XとYに対してビットAND演算をおこなう。
結果は整数のnum値である。
事前条件
Xは整数のnum値でなければならない。
Yは整数のnum値でなければならない。
6.16.1.14. ~ Num¶
~ 演算子、つまりop_notメソッドは、Numに対してビットNOT演算をおこなう。
事前条件
Numは整数のnum値でなければならない。
6.16.1.15. Num << Bit_count¶
<< 演算子、つまりop_shlメソッドは、Numに対してビット左シフト演算をおこなう。
Bit_countが正のとき、NumはBit_countビットだけ左にシフトされる。
Bit_countが負のとき、Numは(-Bit_count)ビットだけ右にシフトされる。下位(-Bit_count)ビットは捨てられる。
Bit_countが0のときは、Numが戻る。
結果は整数のnum値である。
事前条件
Numは整数のnum値でなければならない。
Bit_countは整数のnum値でなければならない。
6.16.1.16. Num >> Bit_count¶
>> 演算子、つまりop_shrメソッドは、Numに対してビット右シフト演算をおこなう。
Bit_countが正のとき、NumはBit_countビットだけ右にシフトされる。下位Bit_countビットは捨てられる。
Bit_countが負のとき、Numは(-Bit_count)ビットだけ左にシフトされる。
Bit_countが0のときは、Numが戻る。
結果は整数のnum値である。
事前条件
Numは整数のnum値でなければならない。
Bit_countは整数のnum値でなければならない。
6.16.1.17. X == Y¶
== 演算子、つまりop_eqメソッドは、ふたつの数値が、Scaleを無視して等しいかどうかを戻す。
事前条件
Yはnum値でなければならない。
例
stdout.print_line((42 == 42.000).repr) # => true
stdout.print_line((42 != 42.000).repr) # => false
stdout.print_line((42 == 24).repr) # => false
stdout.print_line((42 != 24).repr) # => true
6.16.1.18. X <= Y¶
<= 演算子、つまりop_leメソッドは、Xが数値的にY以下かどうかを戻す。
事前条件
Yはnum値でなければならない。
例
:compare <- {(:X :Y)
stdout.print_line('Lt?={} Le?={} Gt?={} Ge?={}'.format(
(X < Y).repr
(X <= Y).repr
(X > Y).repr
(X >= Y).repr))
}
compare(42 42.000) # => Lt?=false Le?=true Gt?=false Ge?=true
compare(42 84) # => Lt?=true Le?=true Gt?=false Ge?=false
compare(42 21) # => Lt?=false Le?=false Gt?=true Ge?=true
6.16.1.19. Num.round¶
roundは、(Dividend=Num, Divisor=1)からなるnum_div値を戻す。
num_div値からどのように値を取り出すかについては、kink/NUM_DIVを見よう。
例
stdout.print_line(1.2345.round.floor(2).repr) # => 1.23
6.16.1.20. Num.abs¶
absはNumの絶対値を戻す。
Numが非負の場合、absはNumを戻す。Numが負の場合、absは(-Num)を戻す。
例
stdout.print_line(42.abs.repr) # => 42
stdout.print_line((-42).abs.repr) # => 42
6.16.1.21. Num.times¶
timesは0から（包含的）、Numまで（排除的）へ、要素ごとに1ずつ増えるiterを戻す。
事前条件
Numは整数のnum値でなければならない。
`Num` ≧ 0
例
5.times.each{(:N)
stdout.print_line(N.repr)
}
# Output:
# 0
# 1
# 2
# 3
# 4
6.16.1.22. Num.up¶
upはNumから、要素ごとに1ずつ増えるiterを戻す。ただし、値がnum型の範囲内に収まる限り。
例
0.5.up.take_front(5).each{(:N)
stdout.print_line(N.repr)
}
# Output:
# 0.5
# 1.5
# 2.5
# 3.5
# 4.5
6.16.1.23. Num.down¶
downはNumから、要素ごとに1ずつ減るiterを戻す。ただし、値がnum型の範囲内に収まる限り。
例
9.5.down.take_front(5).each{(:N)
stdout.print_line(N.repr)
}
# Output:
# 9.5
# 8.5
# 7.5
# 6.5
# 5.5
6.16.1.24. Num.show(...[$config={}])¶
showはNumの文字列表現をstr値として戻す。結果はUIメッセージに使うことが意図される。
showは、num_show_config値を$configに渡す。出力と設定の詳細については、num_show_config型を見よう。
事前条件
$configは、num_show_config値を取る関数でなければならない。
例
stdout.print_line(32767.show) # => 32767
stdout.print_line(32767.show{(:S) S.spec('x') }) # => 7fff
stdout.print_line(32767.show{(:S) S.radix(16) }) # => 7fff
stdout.print_line(32767.show{(:S) S.group_sep(3) }) # => 32,767
showは通常Str.formatから呼ばれる。
stdout.print_line('{} {%04x}'.format(42 255))
# => 42 00ff
6.16.1.25. Num.repr¶
reprは "1.2500", "(-42)" のような文字列を戻す。
6.16.2. NUM.new(Mantissa Scale)¶
newはMantissaとScaleから新しいnum値を作る。
事前条件
Mantissaは整数のnum値でなければならない。
Scaleは整数のnum値でなければならない。
min_mantissa ≦ Mantissa ≦ max_mantissa
0 ≦ Scale ≦ max_scale
例
:NUM.require_from('kink/')
stdout.print_line(NUM.new(12345 2).repr) # => 123.45
6.16.3. NUM.is?(Val)¶
is?はValがnum値であるかどうかを戻す。
6.16.4. NUM.mantissa_bits¶
mantissa_bitsは、整数のnum値8192の定数である。これは、max_mantissaを表せる最小のビット数である。
詳細はnum型のkinkdocを見よう。
6.16.5. NUM.max_mantissa¶
max_mantissaは、整数のnum値 2**8192 - 1 の定数である。これは、Mantissa属性の最大値である。
詳細はnum型のkinkdocを見よう。
6.16.6. NUM.min_mantissa¶
min_mantissaは、整数のnum値 -(2**8192 - 1) の定数である。これは、Mantissa属性の最小値である。
詳細はnum型のkinkdocを見よう。
6.16.7. NUM.max_scale¶
max_scaleは、整数のnum値32767の定数である。これは、Scale属性の最大値である。
詳細はnum型のkinkdocを見よう。
6.16.8. NUM.parse_int(Str ...[$config={}])¶
parse_intはStrをパースして整数のnum値を戻す。
コンフィグメソッド:
• C.radix(Radix): default = 10
• C.on_success($success): default = VAL.identity
• C.on_error($error): default = 例外を投げるサンク
Strが文法に受け入れられ、かつ値が [min_mantissa, max_mantissa] の範囲におさまる場合、parse_intはパースされた整数のnum値を渡して$successを末尾呼び出しする。
Strが文法に受け入れられない場合、または値が [min_mantissa, max_mantissa] の範囲におさまらない場合、parse_intは$errorを引数なしで末尾呼び出しする。
文法
文字列表現は次のふたつの部分からなる。
• Sign: '-', '+', または空
• Digits: 1桁以上のRadix進法の桁
0から9の桁は、'0'から'9'までの文字で表される。
10から35の桁は、'A'から'Z'、または'a'から'z'までの文字で表される。
事前条件
Strはstr値でなければならない。
Radixは[2, 36]の範囲の整数のnum値でなければならない。
$successは整数のnum値を取らなければならない。
$errorはサンクでなければならない。
例
:NUM.require_from('kink/')
stdout.print_line(NUM.parse_int('42').repr) # => 42
stdout.print_line(NUM.parse_int('+42').repr) # => 42
stdout.print_line(NUM.parse_int('-42').repr) # => (-42)
stdout.print_line(NUM.parse_int('ff'){(:C) C.radix(16) }.repr) # => 255
stdout.print_line(NUM.parse_int('fF'){(:C) C.radix(16) }.repr) # => 255
stdout.print_line(NUM.parse_int('-ff'){(:C) C.radix(16) }.repr) # => (-255)
例
:NUM.require_from('kink/')
NUM.parse_int('42'){(:C)
C.on_success{(:N) stdout.print_line(N.repr) }
C.on_error{ stdout.print_line('not valid') }
}
# => 42
NUM.parse_int('*invalid*'){(:C)
C.on_success{(:N) stdout.print_line(N.repr) }
C.on_error{ stdout.print_line('not valid') }
}
# => not valid
6.16.9. NUM.parse_decimal(Str ...[$config={}])¶
parse_decimalはStrから十進数をパースする。
コンフィグメソッド:
• C.on_success($success): default = VAL.identity
• C.on_error($error): default = 例外を投げるサンク
パースされた数値のMantissaは、符号と桁からなる整数値である。
パースされた数値のScaleは、小数点 `.` のあとの桁の個数である。Strが小数点を含まない場合、Scaleは0である。
Strが文法に受け入れられて、Mantissaが [min_mantissa, max_mantissa] の範囲におさまり、Scaleが [0, max_scale] の範囲におさまる場合、parse_decimalは、パースされたnum値を引数として$successを末尾呼び出しする。
Strが文法に受け入れられない場合、またはMantissaかScaleが範囲におさまらない場合、parse_decimalは引数なしで$errorを末尾呼び出しする。
文法
正規表現: [+-]?([0-9]+(\.[0-9]*)?|\.[0-9]+)
事前条件
Strはstr値でなければならない。
$successはnum値を取らなければならない。
$errorはサンクでなければならない。
例
:NUM.require_from('kink/')
stdout.print_line(NUM.parse_decimal('1.2300').repr) # => 1.2300
stdout.print_line(NUM.parse_decimal('.387').repr) # => 0.387
stdout.print_line(NUM.parse_decimal('-42.').repr) # => (-42)
stdout.print_line(NUM.parse_decimal('24').repr) # => 24
例
:NUM.require_from('kink/')
NUM.parse_decimal('3.14'){(:C)
C.on_success{(:N) stdout.print_line(N.repr) }
C.on_error{ stdout.print_line('not valid') }
}
# => 3.14
NUM.parse_decimal('*invalid*'){(:C)
C.on_success{(:N) stdout.print_line(N.repr) }
C.on_error{ stdout.print_line('not valid') }
}
# => not valid
6.16.10. num_show_config型¶
num_show_configはshow_configの部分型（kink/STRを見よう）である。Num.showの出力を設定するのに使われる。
Num.showの結果はふたつのケースに分けられる。
1) num値のScaleが0以下の場合
この場合、出力は “{sign}{grouped_padded_integral_digits}” の形式になる。
2) num値のScaleが0より大きい場合
この場合、基数は10でなければならない。出力は “{sign}{grouped_padded_integral_digits}{decimal_sep}{fractional_digits}” の形式になる。
{sign} の部分
num値が0より小さいとき、{sign}の部分はminus_signメソッドで指定された負の符号になる。
num値が0以上のとき、{sign}の部分はplus_signメソッドで指定された非負の符号になる。
{grouped_padded_integral_digits} の部分
まず、num値の整数部分がradixで指定された基数で、0-9, a-zの桁に変換される。
つぎに、この部分の桁数が、pad_zeroメソッドで指定された最小値よりも少なくならないよう、桁の左側に0が埋められる。
最後に、group_lenで指定されたグループ長によって、桁がグループ化される。グループそれぞれの間には、group_sepで指定された区切り記号が挿入される。
{decimal_sep} の部分
decimal_sepメソッドで指定された記号。
{fractional_digits} の部分
num値の小数部分の十進の桁。
末尾の0は省略されない。したがって、この部分の長さは常にnum値のScaleと等しくなる。
6.16.10.1. C.locale(Locale)¶
localeメソッドを呼ぶと、指定されたロケールの設定を読み込む。
localeメソッドはdecimal_sepとgroup_sepを設定する。
localeが呼ばれなければ、Num.showはどのロケールの情報も使わない。したがって、ランタイムのデフォルトのロケールを使いたい場合でも、明示的にlocaleメソッドを呼ぶ必要がある。
事前条件
Localeはlocale型の値でなければならない。
例
:LOCALE.require_from('kink/')
:Shown <- 3776.24.show{(:S)
S.locale(LOCALE.default)
}
stdout.print_line(Shown)
# Output varies by the runtime default locale
6.16.10.2. C.spec(Spec)¶
specはNum.showの出力を、Spec文字列で指定する。
事前条件
Specはstr値でなければならない。
Specは以下に述べるフィールドをつなげたものでなければならない。
正の符号のフィールド: "+"
"+" を非負の符号として使う。
グルーピングフィールド: ","
グループ長として3を使う。
パディングフィールド: "0{Min_int_digits}"
Min_int_digitsを整数部分の最低限の桁数として使う。
{Min_int_digits}は、正の整数を表す、1つ以上の十進の桁でなければならない。
二進フィールド: "b"
基数として2を使う。
八進フィールド: "o"
基数として8を使う。
十進フィールド: "d"
基数として10を使う。
十六進フィールド: "x"
基数として16を使う。
例
stdout.print_line('{%+04f}'.format(255))
# => +00ff
stdout.print_line('{%,}'.format(12345.6789))
# => 12,345.6789
stdout.print_line('{%b}'.format(42))
# => 101010
stdout.print_line('{%o}'.format(42))
# => 52
stdout.print_line('{%d}'.format(42))
# => 42
stdout.print_line('{%x}'.format(42))
# => 2a
6.16.10.3. C.plus_sign(Plus_sign)¶
plus_signはPlus_signを非負の数の符号として設定する。
デフォルト値は空の文字列 "" である。
事前条件
Plus_signはstr値でなければならない。
例
stdout.print_line(42.show{(:S)
S.plus_sign('+')
})
# => +42
stdout.print_line(0.show{(:S)
S.plus_sign('+')
})
# => +0
stdout.print_line((-10).show{(:S)
S.plus_sign('+')
})
# => -10
6.16.10.4. C.minus_sign(Minus_sign)¶
minus_signはMinus_signを負の数の符号として設定する。
デフォルト値は "-" である。
事前条件
Minus_signはstr値でなければならない。
例
stdout.print_line((-10).show{(:S)
S.minus_sign('minus ')
})
# => minus 10
stdout.print_line(42.show{(:S)
S.minus_sign('minus ')
})
# => 42
stdout.print_line(0.show{(:S)
S.minus_sign('minus ')
})
# => 0
6.16.10.5. C.group_sep(Group_sep)¶
group_sepはGroup_sepをグループ区切りとして設定する。
デフォルト値は "," である。
事前条件
Group_sepはstr値でなければならない。
例
stdout.print_line(12345.6789.show{(:S)
S.group_sep('_')
S.group_len(3)
})
# => 12_345.6789
stdout.print_line(37767.show{(:S)
S.group_sep('_')
S.group_len(2)
S.radix(16)
})
# => 7f_ff
6.16.10.6. C.group_len(Group_len)¶
group_lenはGroup_lenを桁グループの長さとして設定する。
デフォルト値は正の無限大である。つまり、デフォルトではグループ区切りは使われない。
事前条件
Group_lenは1以上の整数のnum値でなければならない。
例
stdout.print_line(12345.6789.show{(:S)
S.group_len(3)
})
# => 12,345.6789
6.16.10.7. C.decimal_sep(Decimal_sep)¶
decimal_sepはDecimal_sepを、整数部と小数部を区切る記号として設定する。
事前条件
Decimal_sepはstr値でなければならない。
例
stdout.print_line(12345.6789.show{(:S)
S.decimal_sep(' . ')
})
# => 12345 . 6789
6.16.10.8. C.pad_zero(Min_int_digits)¶
pad_zeroはMin_int_digitsを、出力される整数部分の桁数の最小値として設定する。
デフォルト値は1である。
事前条件
Min_int_digitsは1以上の整数のnum値でなければならない。
例
stdout.print_line(12345.6789.show{(:S)
S.pad_zero(8)
})
# => 00012345.6789
stdout.print_line((-42).show{(:S)
S.pad_zero(4)
})
# => -0042
stdout.print_line(255.show{(:S)
S.pad_zero(4)
S.radix(16)
})
# => 00ff
6.16.10.9. C.radix(Radix)¶
radixはRadixをshowメソッドの結果の基数として設定する。
デフォルト値は10である。
事前条件
Radixは[2, 36]の範囲内の整数のnum値でなければならない。
showメソッドを呼び出す対象のnum値が整数でないとき、Radixは10でなければならない。
例
stdout.print_line(255.show{(:S)
S.radix(2)
})
# => 11111111
stdout.print_line(255.show{(:S)
S.radix(16)
})
# => ff
stdout.print_line((-255).show{(:S)
S.radix(16)
})
# => -ff