README
¶
Precision Package
The precision package implements functionality for handling the precision of asset prices and quantities following the
YIP-0001 - Asset Price Precision specification.
This package includes functions to ensure that asset prices and quantities are represented with the appropriate level of significant digits and precision, aligning with global standards for price-point (PIP) representation in financial markets.
Installation
To use this package, you can install it using go get:
go get github.com/layer-3/clearsync/precision
Usage
Import the package into your Go code:
import (
"github.com/shopspring/decimal"
"github.com/layer-3/clearsync/pkg/precision"
)
Key Features
ToSignificant function
The ToSignificant function truncates a decimal number to a specified number of significant digits as per the YIP-0001
specification for price representation.
It is crucial for maintaining standard price precision in trading scenarios.
Parameters
input decimal.Decimal: The number to be truncated (non-negative).sigDigits int32: The number of significant digits to retain.
Returns
decimal.Decimal: The truncated decimal number.
Example
result := ToSignificant(decimal.newFromString("123.456"), 4) // Returns 123.4
Validate function
The Validate function ensures that a given decimal number adheres to precision rules specified in the YIP-0001. It
checks that the input is non-negative and its precision does not exceed a specified limit.
Parameters
input decimal.Decimal: The number to be validated.maxPrecision int32: The maximum allowed precision (number of digits after the decimal point).
Returns
error: An error if the input is negative or exceeds the maximum precision.
Example
err := Validate(decimal.newFromString("1.234"), 3) // Returns nil, as the precision is within the limit.
Usage
Import the package into your Go code:
import (
"github.com/shopspring/decimal"
"github.com/layer-3/clearsync/pkg/precision"
)
Feel free to adjust the information or add more details as needed!
Benchmark Results
ToSignificant Benchmark
goos: darwin
goarch: amd64
pkg: github.com/layer-3/clearsync/pkg/precision
cpu: VirtualApple @ 2.50GHz
BenchmarkToSignificant_DecimalWithLeadingZeros-10 4991638 238.6 ns/op 152 B/op 6 allocs/op
BenchmarkToSignificant_TruncateDecimals-10 2944626 407.3 ns/op 312 B/op 12 allocs/op
BenchmarkToSignificant_ExactSignificantDigits-10 7927390 154.6 ns/op 56 B/op 4 allocs/op
BenchmarkToSignificant_IntegralPartSizeGreaterThanSignificantDigits-10 4253004 291.8 ns/op 168 B/op 9 allocs/op
Validate Benchmark
goos: darwin
goarch: amd64
pkg: github.com/layer-3/clearsync/pkg/precision
cpu: VirtualApple @ 2.50GHz
BenchmarkValidate_SuccessfulCase-10 490919691 2.388 ns/op 0 B/op 0 allocs/op
BenchmarkValidate_UnsuccessfulCase-10 8283324 143.4 ns/op 80 B/op 2 allocs/op
Documentation
¶
Overview ¶
Package precision provides functionality for handling the precision of asset prices and quantities in accordance with the YIP-0001 - Asset Price Precision specification.
This package includes functions to ensure that asset prices and quantities are represented with the appropriate level of significant digits and precision, as required in the trading industry. It is designed to align with the global standards for price-point (PIP) representation in FOREX and other financial markets, facilitating configless deployments and network-wide harmony of configuration.
Key Features:
ToSignificant: Truncates a decimal number to a specified number of significant digits, adhering to the YIP-0001 specification for price representation. This function is essential for maintaining the standard price precision in trading scenarios.
Validate: Ensures that the given decimal number does not exceed the maximum allowed precision for prices (18 significant digits) and quantities (8 significant digits). It plays a crucial role in validating input data for trading operations.
This package is an integral part of the Yellow Network's trading infrastructure, ensuring accuracy, consistency, and compliance with established financial market standards.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ToSignificant ¶
ToSignificant truncates coefficient of any decimal.Decimal to a significant number of digits while preserving exponent. The input number is assumed to be non-negative. If the input number has fewer significant digits than requested, it is returned unchanged.
Parameters:
- input: The number to be truncated. The number must be non-negative.
- sigDigits: The number of significant digits to retain in the number. Significant digits are counted from the most significant digit (first non-zero digit) to the specified count. Trailing zeros after the decimal point are not considered significant.
Returns:
- A decimal.Decimal representing the input number truncated to the specified number of significant digits. If the input is zero, it returns zero without modification.
Examples:
Truncating a number to a specific number of significant digits: result := ToSignificant(decimal.NewFromFloat(123.456), 4) // Returns 123.4
Processing a number with fewer significant digits than requested: result := ToSignificant(decimal.NewFromFloat(0.0123), 5) // Returns 0.0123 (unchanged)
Note: - This function does not round the last significant digit; it merely truncates the number. - Negative inputs are not handled by this function and may lead to unintended results.
func Validate ¶
Validate checks if the given number input adheres to precision rules specified in the YIP-0001. The function ensures that the input is non-negative and that its precision does not exceed a limit. Precision in this context is defined as the number of digits after the decimal point for non-integer numbers.
Parameters:
- input: The number to be validated.
- maxPrecision: The maximum allowed precision (number of digits after the decimal point). For example, if maxPrecision is 2, then 1.234 would be considered invalid, since allowed exponent is 10^-2 and the number is 10^-3, while 1.23 would be valid.
Returns:
- An error if the input is negative or if its precision exceeds maxPrecision. If the input is valid according to the specified constraints, the function returns nil.
Example:
Validating a number with a precision that does not exceed the limit: err := Validate(decimal.NewFromFloat(1.234), 3) // Returns nil, as the precision is within the limit.
Validating a negative number or a number with excessive precision: err := Validate(decimal.NewFromFloat(-1.234), 3) // Returns an error, as the input is negative. err := Validate(decimal.NewFromFloat(1.2345), 3) // Returns an error, as the precision exceeds the limit.
Types ¶
This section is empty.
Source Files