Struct icu_experimental::compactdecimal::CompactDecimalFormatter

pub struct CompactDecimalFormatter { /* private fields */ }

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

impl CompactDecimalFormatter

pub fn try_new_short( prefs: CompactDecimalFormatterPreferences, options: CompactDecimalFormatterOptions, ) -> Result<Self, 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(),
);

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

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

📚 Help choosing a constructor

pub fn try_new_short_with_buffer_provider( provider: &(impl BufferProvider + ?Sized), prefs: CompactDecimalFormatterPreferences, options: CompactDecimalFormatterOptions, ) -> Result<Self, 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

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

where D: DataProvider<ShortCompactDecimalFormatDataV1Marker> + DataProvider<DecimalSymbolsV2Marker> + DataProvider<DecimalDigitsV1Marker> + DataProvider<CardinalV1Marker> + ?Sized,

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.

pub fn try_new_long( prefs: CompactDecimalFormatterPreferences, options: CompactDecimalFormatterOptions, ) -> Result<Self, 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(),
);

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

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

📚 Help choosing a constructor

pub fn try_new_long_with_buffer_provider( provider: &(impl BufferProvider + ?Sized), prefs: CompactDecimalFormatterPreferences, options: CompactDecimalFormatterOptions, ) -> Result<Self, 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

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

where D: DataProvider<LongCompactDecimalFormatDataV1Marker> + DataProvider<DecimalSymbolsV2Marker> + DataProvider<DecimalDigitsV1Marker> + DataProvider<CardinalV1Marker> + ?Sized,

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.

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");

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"
);

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

Formats a [FixedDecimal] 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::FixedDecimal;
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(FixedDecimal::from(0)),
    "0"
);
assert_writeable_eq!(
    short_english.format_fixed_decimal(FixedDecimal::from(2)),
    "2"
);
assert_writeable_eq!(
    short_english.format_fixed_decimal(FixedDecimal::from(843)),
    "843"
);
assert_writeable_eq!(
    short_english.format_fixed_decimal(FixedDecimal::from(2207)),
    "2.2K"
);
assert_writeable_eq!(
    short_english.format_fixed_decimal(FixedDecimal::from(15127)),
    "15K"
);
assert_writeable_eq!(
    short_english.format_fixed_decimal(FixedDecimal::from(3010349)),
    "3M"
);
assert_writeable_eq!(
    short_english.format_fixed_decimal(FixedDecimal::from(-13132)),
    "-13K"
);

// The sign display on the FixedDecimal is respected:
assert_writeable_eq!(
    short_english.format_fixed_decimal(
        FixedDecimal::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"
);

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"
);

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

impl Debug for CompactDecimalFormatter

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

Formats the value using the given formatter.