Skip to main content

Crate fy_bcp47

Crate fy_bcp47 

Source
Expand description

§fy-bcp47

crates.io docs.rs CI Coverage MSRV License

fy-bcp47 provides strongly typed, Registry-backed BCP 47 language tags for Rust. It vendors an IANA Language Subtag Registry snapshot, so parsing and validation are deterministic and require no network access at runtime or during ordinary builds.

§Scope

The crate parses and canonicalizes normal tags, pure private-use tags, and grandfathered tags. Registered values and Registry private-use ranges are generated as #[non_exhaustive] enums.

Parsing is case-insensitive, and Display reproduces the Registry spelling: en-us parses and displays as en-US. A parsed tag is a Bcp47Tag — Normal(NormalTag) for registered tags, PrivateUse(PrivateUseTag) for whole x-... tags, or Grandfathered(GrandfatheredTag) for historical tags without a replacement.

Canonicalization applies IANA preferred values, collapses extlang forms into their preferred primary languages, and orders extension sequences by singleton.

The profile intentionally enforces IANA Prefix recommendations for extlang and variant subtags as parse-time constraints. A Prefix matches when its subtags appear in order before the subtag, which RFC 5646 Section 3.1.8 directs through the RFC 4647 extended filtering algorithm; unrelated subtags may still sit between them, so sl-IT-rozaj is accepted. Where a Prefix ends in another variant, RFC 5646 only recommends that the two stay adjacent (sl-rozaj-biske-1994, not sl-rozaj-1994-biske), while this crate requires the dependent variant to follow immediately. The profile is therefore stricter than RFC 5646’s baseline definition of a valid tag: contextually inappropriate combinations such as de-rozaj are rejected even though all individual subtags are registered.

The crate deliberately does not select fonts, dictionaries, hyphenation rules, voices, or locale-sensitive formatting. An accepted language tag does not imply that those resources are available.

RFC 4647 language-range matching and HTTP Accept-Language processing are also outside the current scope.

§Example

use fy_bcp47::{Bcp47Tag, Language, Script};

let Bcp47Tag::Normal(tag) = Bcp47Tag::parse("zh-Hans-CN-u-co-phonebk-x-note")? else {
    unreachable!("the input is a normal BCP 47 tag");
};

assert_eq!(tag.language(), Language::Zh);
assert_eq!(tag.script(), Some(Script::Hans));
assert_eq!(tag.extensions()[0].singleton(), 'u');
assert_eq!(tag.private_use(), ["note"]);

i-klingon is canonicalized to tlh because IANA supplies a Preferred-Value; i-default, which has no replacement, remains Bcp47Tag::Grandfathered.

§Optional Serde support

The core API uses Display/ToString, FromStr, and TryFrom<&str> or TryFrom<String>. Enable the optional serde feature when Bcp47Tag is a field in a serializable user type:

fy-bcp47 = { version = "0.1", features = ["serde"] }

The feature serializes a tag as the same canonical string returned by Display.

§Length limits

By default, each variant sequence, extension sequence, extension-subtag sequence, and private-use subtag sequence is limited to 64 items, and a tag may hold at most 4292 hyphen-separated subtags in total. An input over any of these limits is rejected as invalid; Bcp47Tag::parse never truncates it. The counts are this crate’s policy rather than a standard’s number: RFC 5646 sets no limit on subtag-sequence lengths, and its only hard figure — the 35-character minimum of Section 4.4.1 — fits at most 18 subtags by its own Figure 7 arithmetic. Enable unbounded-lengths only when the caller supplies its own input-size limits, since it removes all of the limits above:

fy-bcp47 = { version = "0.1", features = ["unbounded-lengths"] }

§Registry updates

The source snapshot is data/language-subtag-registry.txt. Updating it is a reviewed source change: refresh the file from IANA, run the test suite, and inspect generated-enum/API changes before committing. A pinned-File-Date test and the build-time private-use-range assertion catch an accidental or partial refresh, and builds never download the Registry.

§License

Licensed under either of:

at your option.

Structs§

Extension
One BCP 47 extension sequence.
GrandfatheredTag
A canonical grandfathered BCP 47 tag with no modern replacement.
NormalTag
A canonical normal BCP 47 tag.
ParseError
An error returned when a tag violates BCP 47 syntax or the bundled Registry.
PrivateUseTag
A canonical pure or trailing private-use sequence.

Enums§

Bcp47Tag
A BCP 47 tag classified by its top-level RFC 5646 form.
Extlang
A Extlang subtag from the bundled IANA Registry snapshot.
Language
A Language subtag from the bundled IANA Registry snapshot.
Region
A Region subtag from the bundled IANA Registry snapshot.
Script
A Script subtag from the bundled IANA Registry snapshot.
Variant
A Variant subtag from the bundled IANA Registry snapshot.