From a3860e23c60c30d4f6aae462015c5bda8b856266 Mon Sep 17 00:00:00 2001 From: Jon Lipstate Date: Tue, 28 Mar 2023 13:09:21 -0700 Subject: [PATCH] doc decimal --- core/strconv/decimal/decimal.odin | 123 +++++++++++++++++++++++++++++- 1 file changed, 119 insertions(+), 4 deletions(-) diff --git a/core/strconv/decimal/decimal.odin b/core/strconv/decimal/decimal.odin index 24ad2ce91..3ae0dd143 100644 --- a/core/strconv/decimal/decimal.odin +++ b/core/strconv/decimal/decimal.odin @@ -8,7 +8,17 @@ Decimal :: struct { decimal_point: int, neg, trunc: bool, } +/* +Sets a Decimal from a given string `s`. The string is expected to represent a float. Stores parsed number in the given Decimal structure. +If parsing fails, the Decimal will be left in an undefined state. +**Inputs** +- d: Pointer to a Decimal struct where the parsed result will be stored +- s: The input string representing the floating-point number + +**Returns** +- ok: A boolean indicating whether the parsing was successful +*/ set :: proc(d: ^Decimal, s: string) -> (ok: bool) { d^ = {} @@ -91,7 +101,16 @@ set :: proc(d: ^Decimal, s: string) -> (ok: bool) { return i == len(s) } +/* +Converts a Decimal to a string representation, using the provided buffer as storage. +**Inputs** +- buf: A byte slice buffer to hold the resulting string +- a: The struct to be converted to a string + +**Returns** +- A string representation of the Decimal +*/ decimal_to_string :: proc(buf: []byte, a: ^Decimal) -> string { digit_zero :: proc(buf: []byte) -> int { for _, i in buf { @@ -100,7 +119,6 @@ decimal_to_string :: proc(buf: []byte, a: ^Decimal) -> string { return len(buf) } - n := 10 + a.count + abs(a.decimal_point) // TODO(bill): make this work with a buffer that's not big enough @@ -129,8 +147,12 @@ decimal_to_string :: proc(buf: []byte, a: ^Decimal) -> string { return string(b[0:w]) } +/* +Trims trailing zeros in the given Decimal, updating the count and decimal_point values as needed. -// trim trailing zeros +**Inputs** +- a: Pointer to the Decimal struct to be trimmed +*/ trim :: proc(a: ^Decimal) { for a.count > 0 && a.digits[a.count-1] == '0' { a.count -= 1 @@ -139,8 +161,15 @@ trim :: proc(a: ^Decimal) { a.decimal_point = 0 } } +/* +Converts a given u64 integer `idx` to its Decimal representation in the provided Decimal struct. +**Used for internal Decimal Operations.** +**Inputs** +- a: Where the result will be stored +- idx: The value to be assigned to the Decimal +*/ assign :: proc(a: ^Decimal, idx: u64) { buf: [64]byte n := 0 @@ -160,9 +189,15 @@ assign :: proc(a: ^Decimal, idx: u64) { a.decimal_point = a.count trim(a) } +/* +Shifts the Decimal value to the right by k positions. +**Used for internal Decimal Operations.** - +**Inputs** +- a: The Decimal struct to be shifted +- k: The number of positions to shift right +*/ shift_right :: proc(a: ^Decimal, k: uint) { r := 0 // read index w := 0 // write index @@ -304,7 +339,15 @@ _shift_left_offsets := [?]struct{delta: int, cutoff: string}{ {18, "173472347597680709441192448139190673828125"}, {19, "867361737988403547205962240695953369140625"}, } +/* +Shifts the decimal of the input value to the left by `k` places +WARNING: asserts `k < 61` + +**Inputs** +- a: The Decimal to be modified +- k: The number of places to shift the decimal to the left +*/ shift_left :: proc(a: ^Decimal, k: uint) #no_bounds_check { prefix_less :: #force_inline proc "contextless" (b: []byte, s: string) -> bool #no_bounds_check { for i in 0..=5) +*/ can_round_up :: proc(a: ^Decimal, nd: int) -> bool { if nd < 0 || nd >= a.count { return false } if a.digits[nd] == '5' && nd+1 == a.count { @@ -395,7 +452,13 @@ can_round_up :: proc(a: ^Decimal, nd: int) -> bool { return a.digits[nd] >= '5' } +/* +Rounds the Decimal at the given digit index +**Inputs** +- a: The Decimal to be modified +- nd: The digit index to round +*/ round :: proc(a: ^Decimal, nd: int) { if nd < 0 || nd >= a.count { return } if can_round_up(a, nd) { @@ -404,7 +467,13 @@ round :: proc(a: ^Decimal, nd: int) { round_down(a, nd) } } +/* +Rounds the Decimal up at the given digit index +**Inputs** +- a: The Decimal to be modified +- nd: The digit index to round up +*/ round_up :: proc(a: ^Decimal, nd: int) { if nd < 0 || nd >= a.count { return } @@ -421,15 +490,61 @@ round_up :: proc(a: ^Decimal, nd: int) { a.count = 1 a.decimal_point += 1 } +/* +Rounds down the decimal value to the specified number of decimal places +**Inputs** +- a: The Decimal value to be rounded down +- nd: The number of decimal places to round down to + +Example: + + import "core:fmt" + import "core:strconv" + strconv_round_down_example :: proc { + d: decimal.Decimal + str := [64]u8{} + ok := decimal.set(&d, "123.456") + decimal.round_down(&d, 5) + fmt.println(decimal.decimal_to_string(str[:], &d)) + } + +Output: + + 123.45 + +*/ round_down :: proc(a: ^Decimal, nd: int) { if nd < 0 || nd >= a.count { return } a.count = nd trim(a) } +/* +Extracts the rounded integer part of a decimal value +**Inputs** +- a: A pointer to the Decimal value to extract the rounded integer part from -// Extract integer part, rounded appropriately. There are no guarantees about overflow. +WARNING: There are no guarantees about overflow. + +**Returns** The rounded integer part of the input decimal value + +Example: + + import "core:fmt" + import "core:strconv" + + strconv_rounded_integer_example :: proc { + d: decimal.Decimal + ok := decimal.set(&d, "123.456") + fmt.println(decimal.rounded_integer(&d)) + } + +Output: + + 123 + +*/ rounded_integer :: proc(a: ^Decimal) -> u64 { if a.decimal_point > 20 { return 0xffff_ffff_ffff_ffff