SubtagRegistry Class
Definition
Namespace: DataStandardizer.LanguageTag
A read-only collection of the records that comprise a loaded copy of the IANA Language Subtag Registry, used to constrain language-tag validation. The constructor is private; load a registry with one of the static CreateFrom… factory methods.
public class SubtagRegistry : IReadOnlyCollection<ISubtagRegistryRecord>
Remarks
Enumerating the registry yields ISubtagRegistryRecord instances (SubtagRegistryTagRecord, SubtagRegistrySubtagRecord, and SubtagRegistryFileDateRecord). The factory methods throw ArgumentNullException for a null argument, and FormatException, naming the line, for content that is not in the record-jar format of RFC 5646 §3.1.1: a line that doesn’t end with CRLF, a blank line, a tab, carriage return or other control character, a line that is neither a field nor a folded line starting with a space, a field that ends with a space, a File-Date, Subtag, Tag, Type, Description, Added or Deprecated field with no value, a File-Date, Added or Deprecated field that isn’t an RFC 3339 full-date (or is one in the year 0000, before the first year a DateTime holds), or a record that is empty, has none or more than one of the File-Date, Subtag and Tag fields, or has no Type that RFC 5646 §3.1.3 defines for it. They also throw FormatException for a registry that breaks the record rules of RFC 5646 §3.1.2: the first record isn’t the File-Date record, there’s a second File-Date record, the File-Date record has another field, a tag or subtag record has no Description or Added field, or a field other than Description, Comments and Prefix appears twice in a record. In a tag or subtag record, fields that RFC 5646 doesn’t define are kept in Fields, and these rules ignore them, as §3.1.2 asks. The File-Date record has the File-Date field alone. Pass a loaded registry to the Bcp47LanguageTag Create / TryCreate overloads, or to the builder’s WithLanguageSubtagRegistry step, to validate against it.
RFC 5646 §3.1.1 ends every line, the last one included, with CRLF, and by default the factory methods follow it. IANA publishes the registry with a line feed alone at the end of each line, so load that file with the overload that takes SubtagRegistryLoadOptions, passing AcceptBareLineFeed. AcceptMissingFinalLineBreak accepts a last line with no line break. Each option accepts only what it names, and a carriage return that no line feed follows is never a line break. The overloads that take options throw ArgumentOutOfRangeException for a value that SubtagRegistryLoadOptions doesn’t define.
A registry and its records are immutable once loaded, so one instance may be shared by every thread. Each record’s fields are parsed into its typed properties when the registry is loaded, and the records of each Type are gathered into the typed lists (Languages, Scripts, GrandfatheredTags and so on), in registry order.
The first time a tag is validated against the registry, or IsGrandfathered is called, the registry builds an index of its subtags and grandfathered tags, and keeps it for every later validation against that registry. The first call to TryGetSubtag builds a second index, from each subtag to its record, and keeps it for every later lookup. Each index is built once per SubtagRegistry instance, by whichever thread uses it first, and is then shared by all threads. Loading a registry builds neither, so a registry that is never used for validation or lookup never pays for them. To validate many tags quickly, load the registry once and reuse it; each newly loaded copy builds its own indexes on first use. Lookups compare subtags and tags case-insensitively (RFC 5646 §2.1.1), and allocate nothing.
A record whose Subtag is a range, such as qaa..qtz, Qaaa..Qabx, QM..QZ or XA..XZ in the IANA registry, registers every subtag in that range (RFC 5646 §3.1.1, §3.1.4). The index holds each subtag in the range, so qaa, en-Qabx and en-XA are valid against the registry, and TryGetSubtag finds the range’s record for qab. Enumerating the registry still yields the one record, with the range as its Subtag.
using DataStandardizer.LanguageTag;
using DataStandardizer.LanguageTag.Registry; // for SubtagRegistryRecordType
var registry = SubtagRegistry.CreateFromFile("language-subtag-registry.txt", SubtagRegistryLoadOptions.AcceptBareLineFeed);
if (registry.TryGetSubtag(SubtagRegistryRecordType.Region, "BU", out var region))
{
Console.WriteLine($"{region.Description[0]}, deprecated {region.Deprecated:yyyy-MM-dd}, use {region.PreferredValue}");
}
var isGrandfathered = registry.IsGrandfathered("i-klingon"); // true
var scriptCount = registry.Scripts.Count;
The CreateFromStream and CreateFromStreamAsync methods read from the stream’s current position and leave the stream open; the caller disposes it. CreateFromFileAsync opens the file for asynchronous, sequential reading.
Properties
| Property | Signature | Notes |
|---|---|---|
Count | int Count { get; } | Number of records in the registry. |
FileDate | DateTime? FileDate { get; } | Date of the registry’s File-Date record. Every loaded registry has one (RFC 5646 §3.1.2), so it is never null. |
Languages | IReadOnlyList<SubtagRegistrySubtagRecord> Languages { get; } | Records of Type language. |
ExtendedLanguages | IReadOnlyList<SubtagRegistrySubtagRecord> ExtendedLanguages { get; } | Records of Type extlang. |
Scripts | IReadOnlyList<SubtagRegistrySubtagRecord> Scripts { get; } | Records of Type script. |
Regions | IReadOnlyList<SubtagRegistrySubtagRecord> Regions { get; } | Records of Type region. |
Variants | IReadOnlyList<SubtagRegistrySubtagRecord> Variants { get; } | Records of Type variant. |
GrandfatheredTags | IReadOnlyList<SubtagRegistryTagRecord> GrandfatheredTags { get; } | Records of Type grandfathered. |
RedundantTags | IReadOnlyList<SubtagRegistryTagRecord> RedundantTags { get; } | Records of Type redundant. |
Methods
Implicit implementation
| Method | Returns | Notes |
|---|---|---|
CreateFromContent(string subtagRegistryContent) | SubtagRegistry | Static. Loads the registry from an in-memory string, with CRLF at the end of every line. |
CreateFromContent(string subtagRegistryContent, SubtagRegistryLoadOptions options) | SubtagRegistry | Static. Loads the registry from an in-memory string, accepting the line breaks that options names as well as CRLF. |
CreateFromContentAsync(string subtagRegistryContent) | Task<SubtagRegistry> | Static. Asynchronous form. |
CreateFromContentAsync(string subtagRegistryContent, CancellationToken cancellationToken) | Task<SubtagRegistry> | Static. Asynchronous form that can be cancelled. Throws OperationCanceledException if cancellationToken is cancelled. |
CreateFromContentAsync(string subtagRegistryContent, SubtagRegistryLoadOptions options, CancellationToken cancellationToken) | Task<SubtagRegistry> | Static. Asynchronous form with options, that can be cancelled. |
CreateFromFile(string subtagRegistryFilePath) | SubtagRegistry | Static. Loads the registry from a file path, with CRLF at the end of every line. netstandard2.0 and net10.0 only. |
CreateFromFile(string subtagRegistryFilePath, SubtagRegistryLoadOptions options) | SubtagRegistry | Static. Loads the registry from a file path, accepting the line breaks that options names as well as CRLF. netstandard2.0 and net10.0 only. |
CreateFromFileAsync(string subtagRegistryFilePath) | Task<SubtagRegistry> | Static. Asynchronous form. netstandard2.0 and net10.0 only. |
CreateFromFileAsync(string subtagRegistryFilePath, CancellationToken cancellationToken) | Task<SubtagRegistry> | Static. Asynchronous form that can be cancelled. Throws OperationCanceledException if cancellationToken is cancelled. netstandard2.0 and net10.0 only. |
CreateFromFileAsync(string subtagRegistryFilePath, SubtagRegistryLoadOptions options, CancellationToken cancellationToken) | Task<SubtagRegistry> | Static. Asynchronous form with options, that can be cancelled. netstandard2.0 and net10.0 only. |
CreateFromStream(Stream stream) | SubtagRegistry | Static. Loads the registry from a stream, with CRLF at the end of every line. |
CreateFromStream(Stream stream, SubtagRegistryLoadOptions options) | SubtagRegistry | Static. Loads the registry from a stream, accepting the line breaks that options names as well as CRLF. |
CreateFromStreamAsync(Stream stream) | Task<SubtagRegistry> | Static. Asynchronous form. |
CreateFromStreamAsync(Stream stream, CancellationToken cancellationToken) | Task<SubtagRegistry> | Static. Asynchronous form that can be cancelled. Throws OperationCanceledException if cancellationToken is cancelled. |
CreateFromStreamAsync(Stream stream, SubtagRegistryLoadOptions options, CancellationToken cancellationToken) | Task<SubtagRegistry> | Static. Asynchronous form with options, that can be cancelled. |
TryGetSubtag(SubtagRegistryRecordType type, string? subtag, out SubtagRegistrySubtagRecord? record) | bool | Gets the record of a subtag of type Language, ExtendedLanguage, Script, Region or Variant. Returns false for an unregistered subtag, a null subtag or any other type. |
TryGetSubtag(SubtagRegistryRecordType type, ReadOnlySpan<char> subtag, out SubtagRegistrySubtagRecord? record) | bool | Span form. |
IsGrandfathered(string? languageTag) | bool | Whether the registry has a grandfathered record for the tag. Returns false for null. |
IsGrandfathered(ReadOnlySpan<char> languageTag) | bool | Span form. |
ToString() | string | Override. Writes the registry in the record-jar format of RFC 5646 §3.1.1, with a %% line between records and CRLF at the end of every line, the last one included, on every platform. The default CreateFrom… methods load the result. |
Applies to
Targets netstandard1.1, netstandard2.0, and net10.0. The CreateFromFile and CreateFromFileAsync methods, including the SubtagRegistryLoadOptions and CancellationToken overloads, exist on netstandard2.0 and net10.0 only; on netstandard1.1, load the registry from a Stream or a string. The public surface is otherwise the same.