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(
   &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( locale: &DataLocale, options: CompactDecimalFormatterOptions ) -> Result<Self, CompactDecimalError>

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

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

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), locale: &DataLocale, options: CompactDecimalFormatterOptions ) -> Result<Self, CompactDecimalError>

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, locale: &DataLocale, options: CompactDecimalFormatterOptions ) -> Result<Self, CompactDecimalError>where D: DataProvider<ShortCompactDecimalFormatDataV1Marker> + DataProvider<DecimalSymbolsV1Marker> + 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.

source

pub fn try_new_long( locale: &DataLocale, options: CompactDecimalFormatterOptions ) -> Result<Self, CompactDecimalError>

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

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

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), locale: &DataLocale, options: CompactDecimalFormatterOptions ) -> Result<Self, CompactDecimalError>

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, locale: &DataLocale, options: CompactDecimalFormatterOptions ) -> Result<Self, CompactDecimalError>where D: DataProvider<LongCompactDecimalFormatDataV1Marker> + DataProvider<DecimalSymbolsV1Marker> + 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.

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.

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

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.

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.

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(
            &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);