Struct fixed_decimal::decimal::FixedDecimal

pub struct FixedDecimal { /* private fields */ }

A struct containing decimal digits with efficient iteration and manipulation by magnitude (power of 10). Supports a mantissa of non-zero digits and a number of leading and trailing zeros, used for formatting and plural selection.

Data Types

The following types can be converted to a FixedDecimal:

• Integers, signed and unsigned
• Strings representing an arbitrary-precision decimal

To create a FixedDecimal with fraction digits, either create it from an integer and then call FixedDecimal::multiplied_pow10, or create it from a string.

Floating point numbers will be supported pending a resolution to #166. In the mean time, a third-party float-to-string library may be used.

Examples

use fixed_decimal::FixedDecimal;

let mut dec = FixedDecimal::from(250);
assert_eq!("250", dec.to_string());

dec.multiply_pow10(-2);
assert_eq!("2.50", dec.to_string());

Implementations

impl FixedDecimal

pub fn digit_at(&self, magnitude: i16) -> u8

Gets the digit at the specified order of magnitude. Returns 0 if the magnitude is out of range of the currently visible digits.

Examples

use fixed_decimal::FixedDecimal;

let dec = FixedDecimal::from(945);
assert_eq!(0, dec.digit_at(-1));
assert_eq!(5, dec.digit_at(0));
assert_eq!(4, dec.digit_at(1));
assert_eq!(9, dec.digit_at(2));
assert_eq!(0, dec.digit_at(3));

pub const fn magnitude_range(&self) -> RangeInclusive<i16>

Gets the visible range of digit magnitudes, in ascending order of magnitude. Call .rev() on the return value to get the range in descending order. Magnitude 0 is always included, even if the number has leading or trailing zeros.

Examples

use fixed_decimal::FixedDecimal;

let mut dec = FixedDecimal::from(120);
assert_eq!(0..=2, dec.magnitude_range());

pub fn multiply_pow10(&mut self, delta: i16) -> Result<(), Error>

Shift the digits by a power of 10, modifying self.

Leading or trailing zeros may be added to keep the digit at magnitude 0 (the last digit before the decimal separator) visible.

Can fail if the change in magnitude pushes the digits out of bounds; the magnitudes of all digits should fit in an i16.

Examples

use fixed_decimal::FixedDecimal;

let mut dec = FixedDecimal::from(42);
assert_eq!("42", dec.to_string());

dec.multiply_pow10(3).expect("Bounds are small");
assert_eq!("42000", dec.to_string());

pub fn multiplied_pow10(self, delta: i16) -> Result<Self, Error>

Shift the digits by a power of 10, consuming self and returning a new object if successful.

Leading or trailing zeros may be added to keep the digit at magnitude 0 (the last digit before the decimal separator) visible.

Can fail if the change in magnitude pushes the digits out of bounds; the magnitudes of all digits should fit in an i16.

Examples

use fixed_decimal::FixedDecimal;

let dec = FixedDecimal::from(42).multiplied_pow10(3).expect("Bounds are small");
assert_eq!("42000", dec.to_string());

pub fn negate(&mut self)

Change the value from negative to positive or from positive to negative, modifying self. Negative zero is supported.

Examples

use fixed_decimal::FixedDecimal;

let mut dec = FixedDecimal::from(42);
assert_eq!("42", dec.to_string());

dec.negate();
assert_eq!("-42", dec.to_string());

dec.negate();
assert_eq!("42", dec.to_string());

// Negative zero example
let zero = FixedDecimal::from(0);
let mut negative_zero = FixedDecimal::from(0);
negative_zero.negate();

assert_eq!("0", zero.to_string());
assert_eq!("-0", negative_zero.to_string());
assert_ne!(zero, negative_zero);

pub fn negated(self) -> Self

Change the value from negative to positive or from positive to negative, consuming self and returning a new object.

Examples

use fixed_decimal::FixedDecimal;

assert_eq!(FixedDecimal::from(-42), FixedDecimal::from(42).negated());

pub fn padded_left(self, digits: u16) -> Self

Zero-pad the number on the left to a particular number of integer digits, returning the result.

Examples

use fixed_decimal::FixedDecimal;

let mut dec = FixedDecimal::from(42);
assert_eq!("42", dec.to_string());

;
assert_eq!("0042", dec.clone().padded_left(4).to_string());

assert_eq!("042", dec.clone().padded_left(3).to_string());

assert_eq!("42", dec.clone().padded_left(2).to_string());

assert_eq!("42", dec.clone().padded_left(1).to_string());

pub fn pad_left(&mut self, digits: u16)

Zero-pad the number on the left to a particular number of integer digits.

Examples

use fixed_decimal::FixedDecimal;

let mut dec = FixedDecimal::from(42);
assert_eq!("42", dec.to_string());

dec.pad_left(4);
assert_eq!("0042", dec.to_string());

dec.pad_left(3);
assert_eq!("042", dec.to_string());

dec.pad_left(2);
assert_eq!("42", dec.to_string());

dec.pad_left(1);
assert_eq!("42", dec.to_string());

pub fn truncated_left(self, magnitude: i16) -> Self

Truncate the number on the left to a particular magnitude, deleting digits if necessary, returning the result.

Examples

use fixed_decimal::FixedDecimal;

let mut dec = FixedDecimal::from(4235);
assert_eq!("4235", dec.to_string());

assert_eq!("4235", dec.clone().truncated_left(5).to_string());

assert_eq!("235", dec.clone().truncated_left(2).to_string());

assert_eq!("35", dec.clone().truncated_left(1).to_string());

assert_eq!("5", dec.clone().truncated_left(0).to_string());

assert_eq!("0", dec.clone().truncated_left(-1).to_string());

pub fn truncate_left(&mut self, magnitude: i16)

Truncate the number on the left to a particular magnitude, deleting digits if necessary.

Examples

use fixed_decimal::FixedDecimal;

let mut dec = FixedDecimal::from(4235);
assert_eq!("4235", dec.to_string());

dec.truncate_left(5);
assert_eq!("4235", dec.to_string());

dec.truncate_left(2);
assert_eq!("235", dec.to_string());

dec.truncate_left(1);
assert_eq!("35", dec.to_string());

dec.truncate_left(0);
assert_eq!("5", dec.to_string());

dec.truncate_left(-1);
assert_eq!("0", dec.to_string());

pub fn padded_right(self, negative_magnitude: u16) -> Self

Zero-pad the number on the right to a particular (negative) magnitude. Will truncate trailing zeros if necessary, but will not truncate other digits, returning the result.

Examples

use fixed_decimal::FixedDecimal;

let mut dec = FixedDecimal::from_str("123.456").unwrap();
assert_eq!("123.456", dec.to_string());

assert_eq!("123.456", dec.clone().padded_right(1).to_string());

assert_eq!("123.456", dec.clone().padded_right(2).to_string());

assert_eq!("123.4560", dec.clone().padded_right(4).to_string());

assert_eq!("123.456000", dec.clone().padded_right(6).to_string());

pub fn pad_right(&mut self, negative_magnitude: u16)

Zero-pad the number on the right to a particular (negative) magnitude. Will truncate trailing zeros if necessary, but will not truncate other digits.

Examples

use fixed_decimal::FixedDecimal;

let mut dec = FixedDecimal::from_str("123.456").unwrap();
assert_eq!("123.456", dec.to_string());

dec.pad_right(1);
assert_eq!("123.456", dec.to_string());

dec.pad_right(2);
assert_eq!("123.456", dec.to_string());

dec.pad_right(4);
assert_eq!("123.4560", dec.to_string());

dec.pad_right(6);
assert_eq!("123.456000", dec.to_string());

pub fn signum(&self) -> Signum

Returns the Signum of this FixedDecimal.

Examples

use fixed_decimal::FixedDecimal;
use fixed_decimal::Signum;

assert_eq!(Signum::AboveZero, FixedDecimal::from(42).signum());
assert_eq!(Signum::PositiveZero, FixedDecimal::from(0).signum());
assert_eq!(Signum::NegativeZero, FixedDecimal::from(0).negated().signum());
assert_eq!(Signum::BelowZero, FixedDecimal::from(-42).signum());

impl FixedDecimal

pub fn try_from_f64(
    float: f64,
    precision: DoublePrecision
) -> Result<Self, Error>

Construct a FixedDecimal from an f64.

Since f64 values do not carry a notion of their precision, the second argument to this function specifies the type of precision associated with the f64. For more information, see DoublePrecision.

This function uses ryu, which is an efficient double-to-string algorithm, but other implementations may yield higher performance; for more details, see icu4x#166.

This function can be made available with the "ryu" feature.

use fixed_decimal::{DoublePrecision, FixedDecimal, RoundingMode};
use writeable::Writeable;

let decimal = FixedDecimal::try_from_f64(
    -5.1,
    DoublePrecision::Magnitude(-2, RoundingMode::Unnecessary)
)
.expect("Finite quantity with limited precision");
assert_eq!(decimal.write_to_string(), "-5.10");

let decimal = FixedDecimal::try_from_f64(
    0.012345678,
    DoublePrecision::Floating
)
.expect("Finite quantity");
assert_eq!(decimal.write_to_string(), "0.012345678");

let decimal = FixedDecimal::try_from_f64(
    12345678000.,
    DoublePrecision::Integer
)
.expect("Finite, integer-valued quantity");
assert_eq!(decimal.write_to_string(), "12345678000");

Negative zero is supported.

use fixed_decimal::{DoublePrecision, FixedDecimal};
use writeable::Writeable;

// IEEE 754 for floating point defines the sign bit separate
// from the mantissa and exponent, allowing for -0.
let negative_zero = FixedDecimal::try_from_f64(
    -0.0,
     DoublePrecision::Integer
).expect("Negative zero");
assert_eq!(negative_zero.write_to_string(), "-0");

Trait Implementations

impl Clone for FixedDecimal

fn clone(&self) -> FixedDecimal

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for FixedDecimal

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for FixedDecimal

fn default() -> Self

Returns a FixedDecimal representing zero.

impl Display for FixedDecimal

Renders the FixedDecimal according to the syntax documented in FixedDecimal::write_to.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<i128> for FixedDecimal

fn from(value: i128) -> Self

Converts to this type from the input type.

impl From<i16> for FixedDecimal

fn from(value: i16) -> Self

Converts to this type from the input type.

impl From<i32> for FixedDecimal

fn from(value: i32) -> Self

Converts to this type from the input type.

impl From<i64> for FixedDecimal

fn from(value: i64) -> Self

Converts to this type from the input type.

impl From<i8> for FixedDecimal

fn from(value: i8) -> Self

Converts to this type from the input type.

impl From<isize> for FixedDecimal

fn from(value: isize) -> Self

Converts to this type from the input type.

impl From<u128> for FixedDecimal

fn from(value: u128) -> Self

Converts to this type from the input type.

impl From<u16> for FixedDecimal

fn from(value: u16) -> Self

Converts to this type from the input type.

impl From<u32> for FixedDecimal

fn from(value: u32) -> Self

Converts to this type from the input type.

impl From<u64> for FixedDecimal

fn from(value: u64) -> Self

Converts to this type from the input type.

impl From<u8> for FixedDecimal

fn from(value: u8) -> Self

Converts to this type from the input type.

impl From<usize> for FixedDecimal

fn from(value: usize) -> Self

Converts to this type from the input type.

impl FromStr for FixedDecimal

type Err = Error

The associated error which can be returned from parsing.

fn from_str(input_str: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl PartialEq<FixedDecimal> for FixedDecimal

fn eq(&self, other: &FixedDecimal) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &FixedDecimal) -> bool

This method tests for !=.

impl Writeable for FixedDecimal

fn write_to<W: Write + ?Sized>(&self, sink: &mut W) -> Result

Render the FixedDecimal as a string of ASCII digits with a possible decimal point.

Examples

use fixed_decimal::FixedDecimal;
use writeable::Writeable;

let dec = FixedDecimal::from(42);
let mut result = String::with_capacity(dec.write_len().capacity());
dec.write_to(&mut result).expect("write_to(String) should not fail");
assert_eq!("42", result);

fn write_len(&self) -> LengthHint

The number of bytes that will be written by FixedDecimal::write_to. Use this function to pre-allocate capacity in the destination buffer.

Examples

use fixed_decimal::FixedDecimal;
use writeable::Writeable;
use writeable::LengthHint;

let dec = FixedDecimal::from(-5000).multiplied_pow10(-2).expect("Bounds are small");
let result = dec.write_to_string();
assert_eq!(LengthHint::exact(6), dec.write_len());

fn write_to_parts<S>(&self, sink: &mut S) -> Result<(), Error> where
    S: PartsWrite + ?Sized, 

Write bytes and Part annotations to the given sink. Errors from the sink are bubbled up. The default implementation delegates to write_to, and doesn’t produce any Part annotations.

fn write_to_string(&self) -> Cow<'_, str>

Creates a new String with the data from this Writeable. Like ToString, but smaller and faster.

impl StructuralPartialEq for FixedDecimal