Crate icu_pattern[][src]

icu_pattern is a utility crate of the ICU4X project.

It includes a Pattern struct which wraps a paid of Parser and Interpolator allowing for parsing and interpolation of ICU placeholder patterns, like “{0} days” or “{0}, {1}” with custom elements and string literals.

Placeholders & Elements

The Parser is generic over any Placeholder which implements FromStr allowing the consumer to parse placeholder patterns such as “{0}, {1}”, “{date}, {time}” or any other.

The Interpolator can interpolate the Pattern against any iterator over Element.

Examples

In the following example we’re going to use a custom Token type, and an Element type which will be either a Token or a string slice.

For the purpose of the example, a higher level interpolate_to_string method is being used.

use icu_pattern::Pattern;
use std::{
    convert::TryInto,
    borrow::Cow,
    fmt::Display,
};

#[derive(Debug, PartialEq)]
enum ExampleToken {
    Year,
    Month,
    Day,
    Hour,
    Minute
}

impl Display for ExampleToken {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "[{:?}]", self)
    }
}

#[derive(Debug, PartialEq)]
enum ExampleElement<'s> {
    Token(ExampleToken),
    Literal(Cow<'s, str>),
}

impl Display for ExampleElement<'_> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Token(token) => token.fmt(f),
            Self::Literal(lit) => lit.fmt(f),
        }
    }
}

let pattern: Pattern<usize> = "{0}, {1}".try_into()
    .expect("Failed to parse a pattern.");

let replacements = vec![
    vec![
        ExampleElement::Token(ExampleToken::Year),
        ExampleElement::Literal("-".into()),
        ExampleElement::Token(ExampleToken::Month),
        ExampleElement::Literal("-".into()),
        ExampleElement::Token(ExampleToken::Day),
    ],
    vec![
        ExampleElement::Token(ExampleToken::Hour),
        ExampleElement::Literal(":".into()),
        ExampleElement::Token(ExampleToken::Minute),
    ],
];

assert_eq!(
    pattern.interpolate_to_string::<ExampleElement, _>(&replacements)
        .expect("Failed to interpolate a pattern."),

    "[Year]-[Month]-[Day], [Hour]:[Minute]"
);

Combinators

In the example above, the replacements will be parsed at compile time and stored on a Vec, which is a collection type that has an implementation for ReplacementProvider trait.

In real use, the consumer may want to use different models of replacement provider, and different element schemas. Because the replacement is an iterator itself, it allows for other, more specialized parsers, to be used to lazily parse particular patterns that are meant to replace the placeholders. This allows for lazy parsing of those specialized patterns to be triggered only if the placeholder pattern encounters a placeholder key that requires given pattern to be used.

Structs

InterpolatedPattern

InterpolatedPattern stores the result of parsing operation as a vector of InterpolatedKind elements.

Interpolator

Placeholder pattern interpolator.

Parser

Placeholder pattern parser.

ParserOptions

Options passed to the constructor of Parser.

Pattern

Pattern stores the result of parsing operation as a vector of PatternToken elements.

Enums

InterpolatedKind

The type returned by the Interpolator iterator. This enum stores references to string literals parsed as part of the pattern and elements returned by the ReplacementProvider.

InterpolatorError

An error returned when interpolating a pattern.

ParserError

An error returned when parsing a pattern.

PatternError

An error returned from a pattern.

PatternToken

A token returned by the Parser.

Traits

ReplacementProvider

A trait which has to be implemented on any type that will be used to provide replacement values for the placeholder pattern during interpolation.