Struct PluralRules

pub struct PluralRules(/* private fields */);

A struct which provides an ability to retrieve an appropriate Plural Category for a given number.

Examples

use icu::locale::locale;
use icu::plurals::{PluralCategory, PluralRules};

let pr = PluralRules::try_new(locale!("en").into(), Default::default())
    .expect("locale should be present");

assert_eq!(pr.category_for(5_usize), PluralCategory::Other);

Implementations

impl PluralRules

pub fn try_new( prefs: PluralRulesPreferences, options: PluralRulesOptions, ) -> Result<Self, DataError>

Constructs a new PluralRules for a given locale and type using compiled data.

Examples

use icu::locale::locale;
use icu::plurals::PluralRules;

let _ = PluralRules::try_new(
    locale!("en").into(),
    Default::default(),
).expect("locale should be present");

✨ Enabled with the compiled_data Cargo feature.

📚 Help choosing a constructor

pub fn try_new_with_buffer_provider( provider: &(impl BufferProvider + ?Sized), prefs: PluralRulesPreferences, options: PluralRulesOptions, ) -> Result<Self, DataError>

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

✨ Enabled with the serde feature.

📚 Help choosing a constructor

pub fn try_new_unstable( provider: &(impl DataProvider<PluralsCardinalV1> + DataProvider<PluralsOrdinalV1> + ?Sized), prefs: PluralRulesPreferences, options: PluralRulesOptions, ) -> Result<Self, DataError>

A version of Self::try_new 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_cardinal( prefs: PluralRulesPreferences, ) -> Result<Self, DataError>

Constructs a new PluralRules for a given locale for cardinal numbers using compiled data.

Cardinal plural forms express quantities of units such as time, currency or distance, used in conjunction with a number expressed in decimal digits (i.e. “2”, not “two”).

For example, English has two forms for cardinals:

• One: 1 day
• Other: 0 days, 2 days, 10 days, 0.3 days

Examples

use icu::locale::locale;
use icu::plurals::{PluralCategory, PluralRules};

let rules = PluralRules::try_new_cardinal(locale!("ru").into()).expect("locale should be present");

assert_eq!(rules.category_for(2_usize), PluralCategory::Few);

✨ Enabled with the compiled_data Cargo feature.

📚 Help choosing a constructor

pub fn try_new_cardinal_with_buffer_provider( provider: &(impl BufferProvider + ?Sized), prefs: PluralRulesPreferences, ) -> Result<Self, DataError>

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

✨ Enabled with the serde feature.

📚 Help choosing a constructor

pub fn try_new_cardinal_unstable( provider: &(impl DataProvider<PluralsCardinalV1> + ?Sized), prefs: PluralRulesPreferences, ) -> Result<Self, DataError>

A version of Self::try_new_cardinal 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_ordinal(prefs: PluralRulesPreferences) -> Result<Self, DataError>

Constructs a new PluralRules for a given locale for ordinal numbers using compiled data.

Ordinal plural forms denote the order of items in a set and are always integers.

For example, English has four forms for ordinals:

• One: 1st floor, 21st floor, 101st floor
• Two: 2nd floor, 22nd floor, 102nd floor
• Few: 3rd floor, 23rd floor, 103rd floor
• Other: 4th floor, 11th floor, 96th floor

Examples

use icu::locale::locale;
use icu::plurals::{PluralCategory, PluralRules};

let rules = PluralRules::try_new_ordinal(
    locale!("ru").into(),
)
.expect("locale should be present");

assert_eq!(rules.category_for(2_usize), PluralCategory::Other);

✨ Enabled with the compiled_data Cargo feature.

📚 Help choosing a constructor

pub fn try_new_ordinal_with_buffer_provider( provider: &(impl BufferProvider + ?Sized), prefs: PluralRulesPreferences, ) -> Result<Self, DataError>

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

✨ Enabled with the serde feature.

📚 Help choosing a constructor

pub fn try_new_ordinal_unstable( provider: &(impl DataProvider<PluralsOrdinalV1> + ?Sized), prefs: PluralRulesPreferences, ) -> Result<Self, DataError>

A version of Self::try_new_ordinal 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 category_for<I: Into<PluralOperands>>(&self, input: I) -> PluralCategory

Returns the Plural Category appropriate for the given number.

Examples

use icu::locale::locale;
use icu::plurals::{PluralCategory, PluralRules};

let pr = PluralRules::try_new(locale!("en").into(), Default::default())
    .expect("locale should be present");

match pr.category_for(1_usize) {
    PluralCategory::One => "One item",
    PluralCategory::Other => "Many items",
    _ => unreachable!(),
};

The method accepts any input that can be calculated into Plural Operands. All unsigned primitive number types can infallibly be converted so they can be used as an input.

For signed numbers and strings, Plural Operands implement TryFrom and FromStr, which should be used before passing the result to category_for().

Examples

use icu::locale::locale;
use icu::plurals::{PluralRules, PluralCategory, PluralOperands};

let operands = PluralOperands::try_from(-5).expect("Failed to parse to operands.");
let operands2: PluralOperands = "5.10".parse().expect("Failed to parse to operands.");

assert_eq!(pr.category_for(operands), PluralCategory::Other);
assert_eq!(pr.category_for(operands2), PluralCategory::Other);

pub fn categories(&self) -> impl Iterator<Item = PluralCategory> + '_

Returns all Plural Categories appropriate for a PluralRules object based on the LanguageIdentifier and PluralRuleType.

The Plural Categories are returned in UTS 35 sorted order.

The category PluralCategory::Other is always included.

Examples

use icu::locale::locale;
use icu::plurals::{PluralCategory, PluralRules};

let pr = PluralRules::try_new(locale!("fr").into(), Default::default())
    .expect("locale should be present");

let mut categories = pr.categories();
assert_eq!(categories.next(), Some(PluralCategory::One));
assert_eq!(categories.next(), Some(PluralCategory::Many));
assert_eq!(categories.next(), Some(PluralCategory::Other));
assert_eq!(categories.next(), None);

Trait Implementations

impl AsRef<PluralRules> for PluralRules

fn as_ref(&self) -> &PluralRules

Converts this type into a shared reference of the (usually inferred) input type.

impl Debug for PluralRules

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

Formats the value using the given formatter.