Struct icu_compactdecimal::CompactDecimalFormatter

source ·

pub struct CompactDecimalFormatter { /* private fields */ }

Expand description

A formatter that renders locale-sensitive compact numbers.

Examples

use icu_compactdecimal::CompactDecimalFormatter;
use icu_locid::locale;
use writeable::assert_writeable_eq;

let short_french = CompactDecimalFormatter::try_new_short_unstable(
   &icu_testdata::unstable(),
   &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_unstable(
            &icu_testdata::unstable(),
            &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 §

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

📚 Help choosing a constructor

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

Examples

use icu_compactdecimal::CompactDecimalFormatter;
use icu_locid::locale;

CompactDecimalFormatter::try_new_short_unstable(
    &icu_testdata::unstable(),
    &locale!("sv").into(),
    Default::default(),
);

source

pub fn try_new_short_with_any_provider( provider: &impl AnyProvider + ?Sized, locale: &DataLocale, options: CompactDecimalFormatterOptions ) -> Result<Self, CompactDecimalError>

Creates a new instance using an AnyProvider.

For details on the behavior of this function, see: Self::try_new_short_unstable

📚 Help choosing a constructor

source

pub fn try_new_short_with_buffer_provider( provider: &impl BufferProvider + ?Sized, locale: &DataLocale, options: CompactDecimalFormatterOptions ) -> Result<Self, CompactDecimalError>

✨ Enabled with the "serde" feature.

Creates a new instance using a BufferProvider.

For details on the behavior of this function, see: Self::try_new_short_unstable

📚 Help choosing a constructor

source

pub fn try_new_long_unstable<D>( data_provider: &D, locale: &DataLocale, options: CompactDecimalFormatterOptions ) -> Result<Self, CompactDecimalError>where D: DataProvider<LongCompactDecimalFormatDataV1Marker> + DataProvider<DecimalSymbolsV1Marker> + DataProvider<CardinalV1Marker> + ?Sized,

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

📚 Help choosing a constructor

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

Examples

use icu_compactdecimal::CompactDecimalFormatter;
use icu_locid::locale;

CompactDecimalFormatter::try_new_long_unstable(
    &icu_testdata::unstable(),
    &locale!("sv").into(),
    Default::default(),
);

source

pub fn try_new_long_with_any_provider( provider: &impl AnyProvider + ?Sized, locale: &DataLocale, options: CompactDecimalFormatterOptions ) -> Result<Self, CompactDecimalError>

Creates a new instance using an AnyProvider.

For details on the behavior of this function, see: Self::try_new_long_unstable

📚 Help choosing a constructor

source

pub fn try_new_long_with_buffer_provider( provider: &impl BufferProvider + ?Sized, locale: &DataLocale, options: CompactDecimalFormatterOptions ) -> Result<Self, CompactDecimalError>

✨ Enabled with the "serde" feature.

Creates a new instance using a BufferProvider.

For details on the behavior of this function, see: Self::try_new_long_unstable

📚 Help choosing a constructor

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.

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_compact_decimal<'l>( &'l self, value: &'l CompactDecimal ) -> Result<FormattedCompactDecimal<'l>, CompactDecimalError>

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_compactdecimal::CompactDecimalFormatter;
use icu_locid::locale;

let [long_french, long_japanese, long_bangla] =
    [locale!("fr"), locale!("ja"), locale!("bn")].map(|locale| {
        CompactDecimalFormatter::try_new_long_unstable(
            &icu_testdata::unstable(),
            &locale.into(),
            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);