Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Denominate ¶ added in v1.17.15
Denominate converts an amount in USD to match the provided currency's precision by shifting the decimal point.
Parameters: - `amount`: The floating-point amount to be denominated. - `denominator`: The number of decimal places to shift the amount by, ranging from 0 to 15.
Returns: - The denominated value as an integer type. - An error if the denominator exceeds 15.
Pitfalls: - Denominator values greater than 15 are not supported and will result in an error. - Be cautious of potential precision loss when working with very large or very small floating-point numbers. - This method directly converts the result to the target integer type, which may result in truncation or rounding.
func ParseDenominated ¶ added in v1.17.15
ParseDenominated converts a denominated value back to its original floating-point representation by shifting the decimal point.
Parameters: - `amount`: The denominated value to be parsed. This should be a numeric type. - `denominator`: The number of decimal places to shift the amount back by, ranging from 0 to 15.
Returns: - The original floating-point value after adjusting for the denominator. - An error if the denominator exceeds 15 or if the operation results in an overflow or invalid number.
Pitfalls:
- **Denominator Limits**: Denominator values greater than 15 are not supported and will result in an error.
- **Overflow and NaN**: If the operation results in a value that is too large, too small, or undefined (NaN), an error will be returned. This can occur with extreme values of `amount` or `denominator`.
- **Precision Loss**: While this function handles typical cases effectively, very large or small numbers may still be subject to floating-point precision issues inherent to the `float64` type. This is particularly important when working with numbers that have more than 15 significant digits.
Usage:
- This function is typically used to reverse the effects of a denomination operation, restoring the original floating-point value from its integer-denominated form.
Types ¶
type Denominated ¶ added in v1.17.15
type Denominated[T denominated] struct {
// contains filtered or unexported fields
}
Denominated represents a value that has been scaled (or "denominated") by a certain number of decimal places, effectively converting it to an integer type.
This struct is useful for scenarios where floating-point numbers need to be converted to integer types to maintain precision, such as when dealing with monetary values.
Type Parameters: - `T`: The underlying integer type that stores the denominated value. This type must satisfy the `denominated` constraint, typically `int64` or `uint64`.
Fields: - `v`: The denominated value stored as an integer of type `T`. This value represents the original floating-point number scaled by `10^d`. - `d`: The denominator, indicating the number of decimal places the original value was shifted by. This is an integer representing the power of 10 used to scale the original value.
Example Usage: Suppose you have a floating-point number `12.345` that you want to store as an integer with three decimal places of precision:
```go var denom Denominated[int64] denom.v = 12345 // The original value (12.345) multiplied by 10^3 denom.d = 3 // Indicates the value was shifted by 3 decimal places ```
In this example, `denom.v` stores `12345` and `denom.d` is `3`, indicating that the original value was `12.345`.
func AsDenom ¶ added in v1.17.15
func AsDenom[T denominated, V uconst.Float](value V, denomination int) (*Denominated[T], error)
AsDenom converts a floating-point value to a Denominated struct by applying the specified denomination. The function uses Denominate to convert the value and then returns a Denominated struct.
Parameters: - `value`: The floating-point value to be denominated. - `denomination`: The number of decimal places to shift the value by. Must be between 0 and 15.
Returns: - A pointer to a Denominated struct containing the denominated value and the denomination. - An error if the denomination exceeds 15 or if the denomination operation results in overflow or precision loss.
func (*Denominated[T]) Denominator ¶ added in v1.17.15
func (d *Denominated[T]) Denominator() int
func (*Denominated[T]) IsValid ¶ added in v1.17.15
func (d *Denominated[T]) IsValid() bool
func (*Denominated[T]) Value ¶ added in v1.17.15
func (d *Denominated[T]) Value() T
type Number ¶
type Number struct {
// contains filtered or unexported fields
}
Number is a versatile numeric representation that can hold different types of numeric values, such as integers, floating-point numbers, unsigned integers, as well as arbitrary-precision numbers (big integers and big floats).
The actual type of the numeric value stored is determined by the field 't' which is of type ValueType. Depending on this type: - For ValueType 'Int', the 'i' field (of type int) stores the value. - For ValueType 'Float', the 'f' field (of type float64) stores the value. - For ValueType 'Uint', the 'ui' field (of type uint64) stores the value. - For ValueType 'BigInt', the 'bi' field (a pointer to big.Int) stores the value. - For ValueType 'BigFloat', the 'bf' field (a pointer to big.Float) stores the value.
The appropriate field should be accessed based on the ValueType to get the correct numeric value. Methods like I(), F(), Ui(), Bi(), and Bf() are provided to retrieve these values safely.
It's also worth noting that the zero value of this struct isn't a valid representation and would need initialization before use. The FromString function can be used to initialize a Number from its string representation.
func FromString ¶
FromString creates a new Number from a string representation. It determines the appropriate type of the number based on the provided string and a flag indicating whether it's a big number.
func NewBigFloat ¶
NewBigFloat creates a new Number from a *big.Float value.
Source Files