pub struct CompactDecimalFormatter { /* private fields */ }
Expand description

A formatter that renders locale-sensitive compact numbers.

§Examples

use icu::experimental::compactdecimal::CompactDecimalFormatter;
use icu::locale::locale;
use writeable::assert_writeable_eq;

let short_french = CompactDecimalFormatter::try_new_short(
   locale!("fr").into(),
   Default::default(),
).unwrap();

let [long_french, long_japanese, long_bangla] = [locale!("fr"), locale!("ja"), locale!("bn")]
    .map(|locale| {
        CompactDecimalFormatter::try_new_long(
            locale.into(),
            Default::default(),
        )
        .unwrap()
    });

/// Supports short and long notations:
assert_writeable_eq!(short_french.format_i64(35_357_670), "35 M");
assert_writeable_eq!(long_french.format_i64(35_357_670), "35 millions");
/// The powers of ten used are locale-dependent:
assert_writeable_eq!(long_japanese.format_i64(3535_7670), "3536万");
/// So are the digits:
assert_writeable_eq!(long_bangla.format_i64(3_53_57_670), "৩.৫ কোটি");

/// The output does not always contain digits:
assert_writeable_eq!(long_french.format_i64(1000), "mille");

Implementations§

source§

impl CompactDecimalFormatter

source

pub fn try_new_short( prefs: CompactDecimalFormatterPreferences, options: CompactDecimalFormatterOptions, ) -> Result<CompactDecimalFormatter, DataError>

Constructor that takes a selected locale and a list of preferences, then collects all compiled data necessary to format numbers in short compact decimal notation for the given locale.

Enabled with the compiled_data Cargo feature.

📚 Help choosing a constructor

§Examples
use icu::experimental::compactdecimal::CompactDecimalFormatter;
use icu::locale::locale;

CompactDecimalFormatter::try_new_short(
    locale!("sv").into(),
    Default::default(),
);
source

pub fn try_new_short_with_any_provider( provider: &(impl AnyProvider + ?Sized), prefs: CompactDecimalFormatterPreferences, options: CompactDecimalFormatterOptions, ) -> Result<CompactDecimalFormatter, DataError>

A version of [Self :: try_new_short] that uses custom data provided by an AnyProvider.

📚 Help choosing a constructor

source

pub fn try_new_short_with_buffer_provider( provider: &(impl BufferProvider + ?Sized), prefs: CompactDecimalFormatterPreferences, options: CompactDecimalFormatterOptions, ) -> Result<CompactDecimalFormatter, DataError>

A version of [Self :: try_new_short] that uses custom data provided by a BufferProvider.

Enabled with the serde feature.

📚 Help choosing a constructor

source

pub fn try_new_short_unstable<D>( provider: &D, prefs: CompactDecimalFormatterPreferences, options: CompactDecimalFormatterOptions, ) -> Result<CompactDecimalFormatter, DataError>

A version of Self::try_new_short that uses custom data provided by a DataProvider.

📚 Help choosing a constructor

⚠️ The bounds on provider may change over time, including in SemVer minor releases.
source

pub fn try_new_long( prefs: CompactDecimalFormatterPreferences, options: CompactDecimalFormatterOptions, ) -> Result<CompactDecimalFormatter, DataError>

Constructor that takes a selected locale and a list of preferences, then collects all compiled data necessary to format numbers in short compact decimal notation for the given locale.

Enabled with the compiled_data Cargo feature.

📚 Help choosing a constructor

§Examples
use icu::experimental::compactdecimal::CompactDecimalFormatter;
use icu::locale::locale;

CompactDecimalFormatter::try_new_long(
    locale!("sv").into(),
    Default::default(),
);
source

pub fn try_new_long_with_any_provider( provider: &(impl AnyProvider + ?Sized), prefs: CompactDecimalFormatterPreferences, options: CompactDecimalFormatterOptions, ) -> Result<CompactDecimalFormatter, DataError>

A version of [Self :: try_new_long] that uses custom data provided by an AnyProvider.

📚 Help choosing a constructor

source

pub fn try_new_long_with_buffer_provider( provider: &(impl BufferProvider + ?Sized), prefs: CompactDecimalFormatterPreferences, options: CompactDecimalFormatterOptions, ) -> Result<CompactDecimalFormatter, DataError>

A version of [Self :: try_new_long] that uses custom data provided by a BufferProvider.

Enabled with the serde feature.

📚 Help choosing a constructor

source

pub fn try_new_long_unstable<D>( provider: &D, prefs: CompactDecimalFormatterPreferences, options: CompactDecimalFormatterOptions, ) -> Result<CompactDecimalFormatter, DataError>

A version of Self::try_new_long that uses custom data provided by a DataProvider.

📚 Help choosing a constructor

⚠️ The bounds on provider may change over time, including in SemVer minor releases.
source

pub fn format_i64(&self, value: i64) -> FormattedCompactDecimal<'_>

Formats an integer in compact decimal notation using the default precision settings.

The result may have a fractional digit only if it is compact and its significand is less than 10. Trailing fractional 0s are omitted, and a sign is shown only for negative values.

§Examples
use icu::experimental::compactdecimal::CompactDecimalFormatter;
use icu::locale::locale;
use writeable::assert_writeable_eq;

let short_english = CompactDecimalFormatter::try_new_short(
    locale!("en").into(),
    Default::default(),
)
.unwrap();

assert_writeable_eq!(short_english.format_i64(0), "0");
assert_writeable_eq!(short_english.format_i64(2), "2");
assert_writeable_eq!(short_english.format_i64(843), "843");
assert_writeable_eq!(short_english.format_i64(2207), "2.2K");
assert_writeable_eq!(short_english.format_i64(15_127), "15K");
assert_writeable_eq!(short_english.format_i64(3_010_349), "3M");
assert_writeable_eq!(short_english.format_i64(-13_132), "-13K");

The result is the nearest such compact number, with halfway cases- rounded towards the number with an even least significant digit.

assert_writeable_eq!(short_english.format_i64(999_499), "999K");
assert_writeable_eq!(short_english.format_i64(999_500), "1M");
assert_writeable_eq!(short_english.format_i64(1650), "1.6K");
assert_writeable_eq!(short_english.format_i64(1750), "1.8K");
assert_writeable_eq!(short_english.format_i64(1950), "2K");
assert_writeable_eq!(short_english.format_i64(-1_172_700), "-1.2M");
source

pub fn format_f64( &self, value: f64, ) -> Result<FormattedCompactDecimal<'_>, LimitError>

Formats a floating-point number in compact decimal notation using the default precision settings.

The result may have a fractional digit only if it is compact and its significand is less than 10. Trailing fractional 0s are omitted, and a sign is shown only for negative values.

Enabled with the ryu Cargo feature.

§Examples
use icu::experimental::compactdecimal::CompactDecimalFormatter;
use icu::locale::locale;
use writeable::assert_writeable_eq;

let short_english = CompactDecimalFormatter::try_new_short(
    locale!("en").into(),
    Default::default(),
)
.unwrap();

assert_writeable_eq!(short_english.format_f64(0.0).unwrap(), "0");
assert_writeable_eq!(short_english.format_f64(2.0).unwrap(), "2");
assert_writeable_eq!(short_english.format_f64(843.0).unwrap(), "843");
assert_writeable_eq!(short_english.format_f64(2207.0).unwrap(), "2.2K");
assert_writeable_eq!(short_english.format_f64(15_127.0).unwrap(), "15K");
assert_writeable_eq!(short_english.format_f64(3_010_349.0).unwrap(), "3M");
assert_writeable_eq!(short_english.format_f64(-13_132.0).unwrap(), "-13K");

The result is the nearest such compact number, with halfway cases- rounded towards the number with an even least significant digit.

assert_writeable_eq!(short_english.format_f64(999_499.99).unwrap(), "999K");
assert_writeable_eq!(short_english.format_f64(999_500.00).unwrap(), "1M");
assert_writeable_eq!(short_english.format_f64(1650.0).unwrap(), "1.6K");
assert_writeable_eq!(short_english.format_f64(1750.0).unwrap(), "1.8K");
assert_writeable_eq!(short_english.format_f64(1950.0).unwrap(), "2K");
assert_writeable_eq!(
    short_english.format_f64(-1_172_700.0).unwrap(),
    "-1.2M"
);
source

pub fn format_fixed_decimal( &self, value: &Signed<UnsignedFixedDecimal>, ) -> FormattedCompactDecimal<'_>

Formats a SignedFixedDecimal by automatically scaling and rounding it.

The result may have a fractional digit only if it is compact and its significand is less than 10. Trailing fractional 0s are omitted.

Because the FixedDecimal is mutated before formatting, this function takes ownership of it.

§Examples
use fixed_decimal::SignedFixedDecimal;
use icu::experimental::compactdecimal::CompactDecimalFormatter;
use icu::locale::locale;
use writeable::assert_writeable_eq;

let short_english = CompactDecimalFormatter::try_new_short(
    locale!("en").into(),
    Default::default(),
)
.unwrap();

assert_writeable_eq!(
    short_english.format_fixed_decimal(&SignedFixedDecimal::from(0)),
    "0"
);
assert_writeable_eq!(
    short_english.format_fixed_decimal(&SignedFixedDecimal::from(2)),
    "2"
);
assert_writeable_eq!(
    short_english.format_fixed_decimal(&SignedFixedDecimal::from(843)),
    "843"
);
assert_writeable_eq!(
    short_english.format_fixed_decimal(&SignedFixedDecimal::from(2207)),
    "2.2K"
);
assert_writeable_eq!(
    short_english.format_fixed_decimal(&SignedFixedDecimal::from(15127)),
    "15K"
);
assert_writeable_eq!(
    short_english.format_fixed_decimal(&SignedFixedDecimal::from(3010349)),
    "3M"
);
assert_writeable_eq!(
    short_english.format_fixed_decimal(&SignedFixedDecimal::from(-13132)),
    "-13K"
);

// The sign display on the FixedDecimal is respected:
assert_writeable_eq!(
    short_english.format_fixed_decimal(
        &SignedFixedDecimal::from(2500)
            .with_sign_display(fixed_decimal::SignDisplay::ExceptZero)
    ),
    "+2.5K"
);

The result is the nearest such compact number, with halfway cases- rounded towards the number with an even least significant digit.

assert_writeable_eq!(
    short_english.format_fixed_decimal(&"999499.99".parse().unwrap()),
    "999K"
);
assert_writeable_eq!(
    short_english.format_fixed_decimal(&"999500.00".parse().unwrap()),
    "1M"
);
assert_writeable_eq!(
    short_english.format_fixed_decimal(&"1650".parse().unwrap()),
    "1.6K"
);
assert_writeable_eq!(
    short_english.format_fixed_decimal(&"1750".parse().unwrap()),
    "1.8K"
);
assert_writeable_eq!(
    short_english.format_fixed_decimal(&"1950".parse().unwrap()),
    "2K"
);
assert_writeable_eq!(
    short_english.format_fixed_decimal(&"-1172700".parse().unwrap()),
    "-1.2M"
);
source

pub fn format_compact_decimal<'l>( &'l self, value: &'l CompactDecimal, ) -> Result<FormattedCompactDecimal<'l>, ExponentError>

Formats a CompactDecimal object according to locale data.

This is an advanced API; prefer using Self::format_i64() in simple cases.

Since the caller specifies the exact digits that are displayed, this allows for arbitrarily complex rounding rules. However, contrary to FixedDecimalFormatter::format(), this operation can fail, because the given CompactDecimal can be inconsistent with the locale data; for instance, if the locale uses lakhs and crores and millions are requested, or vice versa, this function returns an error.

The given CompactDecimal should be constructed using Self::compact_exponent_for_magnitude() on the same CompactDecimalFormatter object. Specifically, formatter.format_compact_decimal(n) requires that n.exponent() be equal to formatter.compact_exponent_for_magnitude(n.significand().nonzero_magnitude_start() + n.exponent()).

§Examples
use fixed_decimal::CompactDecimal;

let about_a_million = CompactDecimal::from_str("1.20c6").unwrap();
let three_million = CompactDecimal::from_str("+3c6").unwrap();
let ten_lakhs = CompactDecimal::from_str("10c5").unwrap();
assert_writeable_eq!(
    short_french
        .format_compact_decimal(&about_a_million)
        .unwrap(),
    "1,20 M"
);
assert_writeable_eq!(
    long_french
        .format_compact_decimal(&about_a_million)
        .unwrap(),
    "1,20 million"
);

assert_writeable_eq!(
    short_french.format_compact_decimal(&three_million).unwrap(),
    "+3 M"
);
assert_writeable_eq!(
    long_french.format_compact_decimal(&three_million).unwrap(),
    "+3 millions"
);

assert_writeable_eq!(
    long_bangla.format_compact_decimal(&ten_lakhs).unwrap(),
    "১০ লাখ"
);

assert_eq!(
    long_bangla
        .format_compact_decimal(&about_a_million)
        .err()
        .unwrap()
        .to_string(),
    "Expected compact exponent 5 for 10^6, got 6",
);
assert_eq!(
    long_french
        .format_compact_decimal(&ten_lakhs)
        .err()
        .unwrap()
        .to_string(),
    "Expected compact exponent 6 for 10^6, got 5",
);

/// Some patterns omit the digits; in those cases, the output does not
/// contain the sequence of digits specified by the CompactDecimal.
let a_thousand = CompactDecimal::from_str("1c3").unwrap();
assert_writeable_eq!(
    long_french.format_compact_decimal(&a_thousand).unwrap(),
    "mille"
);
source

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

Returns the compact decimal exponent that should be used for a number of the given magnitude when using this formatter.

§Examples
use icu::experimental::compactdecimal::CompactDecimalFormatter;
use icu::locale::locale;

let [long_french, long_japanese, long_bangla] = [
    locale!("fr").into(),
    locale!("ja").into(),
    locale!("bn").into(),
]
.map(|locale| {
    CompactDecimalFormatter::try_new_long(locale, Default::default())
        .unwrap()
});
/// French uses millions.
assert_eq!(long_french.compact_exponent_for_magnitude(6), 6);
/// Bangla uses lakhs.
assert_eq!(long_bangla.compact_exponent_for_magnitude(6), 5);
/// Japanese uses myriads.
assert_eq!(long_japanese.compact_exponent_for_magnitude(6), 4);

Trait Implementations§

source§

impl Debug for CompactDecimalFormatter

source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> IntoEither for T

source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

source§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> ErasedDestructor for T
where T: 'static,

source§

impl<T> MaybeSendSync for T
where T: Send + Sync,