BenBurgers.InternationalStandards.Iso 0.4.0

There is a newer version of this package available.
See the version list below for details.
dotnet add package BenBurgers.InternationalStandards.Iso --version 0.4.0                
NuGet\Install-Package BenBurgers.InternationalStandards.Iso -Version 0.4.0                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="BenBurgers.InternationalStandards.Iso" Version="0.4.0" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add BenBurgers.InternationalStandards.Iso --version 0.4.0                
#r "nuget: BenBurgers.InternationalStandards.Iso, 0.4.0"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install BenBurgers.InternationalStandards.Iso as a Cake Addin
#addin nuget:?package=BenBurgers.InternationalStandards.Iso&version=0.4.0

// Install BenBurgers.InternationalStandards.Iso as a Cake Tool
#tool nuget:?package=BenBurgers.InternationalStandards.Iso&version=0.4.0                

Contents

Introduction

Thank you for choosing this package.

The BenBurgers.InternationalStandards.Iso package contains codes and features that belong to standards of the International Organization for Standardization (ISO).

The International Organization for Standardization (ISO) is an international standard development organization composed of representatives from the national standards organizations of member countries. The organization develops and publishes standardization in all technical and nontechnical fields other than electrical and electronic engineering.[^1]

[^1]: Wikipedia, downloaded at 31 October 2022, 23:33 CET.

You are kindly encouraged to buy the standards you use at the ISO Store in order to fund their mission.

GitHub Sponsors

If you like my contributions, please have a look at my GitHub Sponsors profile. My open source contributions are available free of charge (but subject to licenses) and the contributions are made entirely in my free time, but sponsorship would be sincerely appreciated. Thank you.

If possible, please also buy a standard from the respective Maintenance Agency or ISO itself to cover the costs of the Maintenance Agencies and the ISO in maintaining the standards.

Packages

These are the packages that concern the ISO standards:

Name Description
BenBurgers.InternationalStandards.Iso The main package with the codes and metadata.
BenBurgers.InternationalStandards.Iso.EFCore Features for storing codes using Entity Framework Core.
BenBurgers.InternationalStandards.Iso.EFCore.SqlServer Features for storing codes using Entity Framework Core and SQL Server.
BenBurgers.InternationalStandards.Iso.IO Features for reading Code Tables from authorities.
BenBurgers.InternationalStandards.Iso.Json Features for serializing and deserializing codes in JSON.

Please refer to NuGet to download the packages and GitHub for the source code.

Manual

Supported ISO standards

The following are the currently supported ISO standards.

Name Description
ISO 639 Language codes
ISO 3166 Country codes
ISO 4217 Currency codes
ISO 8601 Date and Time formatting

ISO 639 language codes

The Austrian Standards is the Maintenance Agency of ISO 639-1 codes. Only they can designate ISO 639-1 codes. This work is a derivation and enhancement and anything other than ISO 639-1 is the responsibility of the respective copyright holders.

The Library of Congress is the Maintenance Agency of ISO 639-2 codes. Only they can designate ISO 639-2 codes. This work is a derivation and enhancement and anything other than ISO 639-2 is the responsibility of the respective copyright holders.

The SIL International is the Maintenance Agency of ISO 639-3 codes. Only they can designate ISO 639-3 codes. This work is a derivation and enhancement and anything other than ISO 639-3 is the responsibility of the respective copyright holders.

The ISO 639-3 codes in this version are effective from 11 March 2022 until the Maintenance Agency publishes new codes.

Codes

The Iso639Code enum in the BenBurgers.InternationalStandards.Iso.Iso639 namespace defines the codes from the ISO 639 language codes standard. In order to effectively store, read, write and transfer the codes, extension methods have been made available in Iso639CodeExtensions.

Part 1

Before requesting a value for ISO 639-1, it is possible to request whether a Part 1 code has been designated by calling the HasPart1 method.

Example
using BenBurgers.InternationalStandards.Iso.Iso639;

const Iso639Code Value = Iso639Code.Mayan_Epigraphic;
var hasPart1 = Value.HasPart1(allowDeprecated: true); // false
Console.Write(hasPart1.ToString());

/*
* Output:
* 
* false
*/

The method ToPart1 returns the Alpha-2 code for ISO 639-1 or null if it has not been designated or deprecated if deprecated codes are not allowed.

Example
using BenBurgers.InternationalStandards.Iso.Iso639;

const Iso639Code Value = Iso639Code.English;
var part1 = Value.ToPart1(allowDeprecated: true); // en
Console.Write(part1);

/*
* Output:
* 
* en
*/
Part 2

Before requesting a value for ISO 639-2T or ISO 639-2B, it is possible to request whether a Part 2 code has been designated by calling the HasPart2 method.

Example
using BenBurgers.InternationalStandards.Iso.Iso639;

const Iso639Code Value = Iso639Code.Dutch_Flemish;
var hasPart2 = Value.HasPart2(); // true
Console.Write(hasPart2.ToString());

/*
* Output:
* 
* true
*/

The method ToPart2 returns the Alpha-3 code for either ISO 639-2T or ISO 639-2B, or null if it has not been designated or deprecated if deprecated codes are not allowed.

Example
using BenBurgers.InternationalStandards.Iso.Iso639;

const Iso639Code Value = Iso639Code.French;
var part2T = Value.ToPart2(Iso639Part2Type.Terminological); // fra
var part2B = Value.ToPart2(Iso639Part2Type.Bibliographic); // fre
Console.WriteLine(part2T);
Console.WriteLine(part2B);

/*
* Output:
*
* fra
* fre
*/
Part 3

Before requesting a value for ISO 639-3, it is possible to request whether a Part 3 code has been designated by calling the HasPart3 method.

Example
using BenBurgers.InternationalStandards.Iso.Iso639;

const Iso639Code Value = Iso639Code.Frisian_Western;
var hasPart3 = Value.HasPart3(); // true
Console.Write(hasPart3.ToString());

/*
* Output:
*
* true
*/

The method ToPart3 returns the Alpha-3 code for ISO 639-3, or null if it has not been designated or deprecated if deprecated codes are not allowed.

Example
using BenBurgers.InternationalStandards.Iso.Iso639;

const Iso639Code Value = Iso639Code.Hindi;
var part3 = Value.ToPart3(); // hin
Console.Write(part3);

/*
* Output:
*
* hin
*/
Model

For requesting a code's metadata all at once, the method ToModel returns a record containing the metadata.

Example
using BenBurgers.InternationalStandards.Iso.Iso639;

const Iso639Code Value = Iso639Code.Hittite;
var (part1, part2T, part2B, part3, scope, languageType, refName, printName, invertedName) = Value.ToModel();
Console.WriteLine(part2T);
Console.WriteLine(part2B);
Console.WriteLine(part3);
Console.WriteLine(scope.ToString());
Console.WriteLine(languageType.ToString());

/*
* Output:
*
* hit
* hit
* hit
* Individual
* Ancient
*/
Language Type

The ISO 639 standard defines the following language types:

Name
Ancient
Constructed
Extinct
Genetic
GeneticAncient
GeneticLike
Geographic
Historical
Living
Special

For their descriptions and usages, please refer to SIL International's page about language types.

Example
using BenBurgers.InternationalStandards.Iso.Iso639;

const Iso639Code Value = Iso639Code.Indonesian;
var languageType = Value.GetLanguageType(); // Iso639LanguageType.Living
Console.Write(languageType.ToString());

/*
* Output:
* 
* Living
*/
From text

Converting a code from text is possible with the ToIso639 and TryToIso639 extension methods on string.

Example
using BenBurgers.InternationalStandards.Iso.Iso639;

const string Value = "hke";
var code = Value.ToIso639(); // Iso639Code.Hunde
Console.Write(code.ToString());

/*
* Output:
*
* Hunde
*/
Example
using BenBurgers.InternationalStandards.Iso.Iso639;

const string Value = "yyy"
if (Value.TryToIso639(out var code)) {
    Console.WriteLine("Valid");
    Console.WriteLine(code!.ToString());
} else {
    Console.Write("Invalid");
}

/*
* Output:
*
* Invalid
*/

ISO 3166 country codes

The ISO 3166 Maintenance Agency is the sole authority of ISO 3166 codes. Only they can designate ISO 3166 codes. This work is a derivation and enhancement and anything other than the ISO 3166 codes is the responsibility of the respective copyright holders.

Codes

The Iso3166Code enum in the BenBurgers.InternationalStandards.Iso.Iso3166 namespace defines the codes from the ISO 3166 country codes standard. In order to effectively store, read, write and transfer the codes, extension methods have been made available in Iso3166CodeExtensions.

Alpha-2

To request the Alpha-2 two-letter code for ISO 3166 codes, the ToAlpha2 method may be called.

Example
using BenBurgers.InternationalStandards.Iso.Iso3166;

const Iso3166Code Value = Iso3166Code.Thailand;
var alpha2 = Value.ToAlpha2(); // TH
Console.Write(alpha2);

/*
* Output:
*
* TH
*/
Alpha-3

To request the Alpha-3 three-letter code for ISO 3166 codes, the ToAlpha3 method may be called.

Example
using BenBurgers.InternationalStandards.Iso.Iso3166;

const Iso3166Code Value = Iso3166Code.Tuvalu;
var alpha3 = Value.ToAlpha3();
Console.Write(alpha3);

/*
* Output:
*
* TUV
*/
Numeric

The numeric value of ISO 3166 codes is the integer value of the enum field.

Example
using BenBurgers.InternationalStandards.Iso.Iso3166;

const Iso3166Code Value = Iso3166Code.UnitedStatesOfAmerica;
var numeric = (int)Value; // 840
Console.Write(numeric.ToString());

/*
* Output:
*
* 840
*/
Model

For requesting a code's metadata all at once, the method ToModel returns a record containing the metadata.

Example
using BenBurgers.InternationalStandards.Iso.Iso3166;

const Iso3166Code Value = Iso3166Code.Ukraine;
var (numeric, alpha2, alpha3) = Value.ToModel();
Console.WriteLine(numeric.ToString());
Console.WriteLine(alpha2.Value);
Console.WriteLine(alpha3.Value);

/*
* Output:
*
* 804
* UA
* UKR
*/
Name

The extension method GetName provides a localized name (in one of the supported cultures of the packages) for the country. These names are not part of the ISO 3166 standard, but provided by the package itself.

Example
using BenBurgers.InternationalStandards.Iso.Iso3166;
using System.Globalization;

const Iso3166Code Value = Iso3166Code.Bhutan;
var culture = new CultureInfo("fr");
var name = Value.GetName(culture, Iso3166NameVariant.Long); // royaume du Bhoutan
Console.Write(name);

/*
* Output:
*
* royaume du Bhoutan
*/
From text

The ToIso3166 and TryToIso3166 methods convert a code from string to the enum value.

Example
using BenBurgers.InternationalStandards.Iso.Iso3166;

const string Value = "ZM";
var code = Value.ToIso3166(); // Iso3166Code.Zambia
Console.WriteLine(code.ToString());

/*
* Output:
*
* Zambia
*/

Using TryToIso3166:

Example
using BenBurgers.InternationalStandards.Iso.Iso3166;

const string Value = "AAA";
if (Value.TryToIso3166(out var code)) {
    Console.WriteLine("Valid");
    Console.WriteLine(code!.ToString());
} else {
    Console.Write("Invalid");
}

/*
* Output:
*
* Invalid
*/

ISO 4217 currency codes

The SIX Financial Information AG is the Maintenance Agency of ISO 4217 codes. Only they can designate ISO 4217 codes. This work is a derivation and enhancement and anything other than the ISO 4217 codes is the responsibility of the respective copyright holders.

The ISO 4217 codes in this version were published at 23 September 2022.

Codes

The Iso4217Code enum in the BenBurgers.InternationalStandards.Iso.Iso4217 namespace defines the codes from the ISO 4217 currency codes standard. In order to effectively store, read, write and transfer the codes, extension methods have been made available in Iso4217CodeExtensions.

Alpha-3

To retrieve the Alpha-3 three-letter code of the ISO 4217 code, one may call the method ToAlpha.

Example
using BenBurgers.InternationalStandards.Iso.Iso4217;

const Iso4217Code Value = Iso4217Code.Euro;
var alpha = Value.ToAlpha(); // EUR
Console.Write(alpha);

/*
* Output:
*
* EUR
*/
Numeric

The ISO 4217 numeric code is the integer value.

Example
using BenBurgers.InternationalStandards.Iso.Iso4217;

const Iso4217Code Value = Iso4217Code.USDollar;
var numeric = (int)Value; // 840
Console.Write(numeric.ToString());

/*
* Output:
*
* 840
*/
Model

A model with all metadata can be requested with the method ToModel.

Example
using BenBurgers.InternationalStandards.Iso.Iso4217;

const Iso4217Code Value = Iso4217Code.PoundSterling;
var model = Value.ToModel();
Console.WriteLine(model.CurrencyName);
Console.WriteLine(model.Currency!.Value);
Console.WriteLine(model.CurrencyNumber.ToString());
Console.WriteLine(model.CurrencyMinorUnits!.ToString());
Console.WriteLine(string.Join(", ", model.Entities));

/*
* Output:
*
* Pound Sterling
* GBP
* 826
* 2
* GUERNSEY, ISLE OF MAN, JERSEY, UNITED KINGDOM OF GREAT BRITAIN AND NORTHERN IRELAND (THE)
*/
Entities

The method GetEntities returns the entities that trade a currency.

Example
using BenBurgers.InternationalStandards.Iso.Iso4217;

const Iso4217Code Value = Iso4217Code.IndianRupee;
var entities = Value.GetEntities();
Console.Write(string.Join(", ", entities));

/*
* Output:
*
* BHUTAN, INDIA
*/
Reference Name

To get an ISO 4217 code's reference name, the method GetReferenceName may be called.

Example
using BenBurgers.InternationalStandards.Iso.Iso4217;

const Iso4217Code Value = Iso4217Code.IcelandKrona;
var referenceName = Value.GetReferenceName(); // "Iceland Krona"
Console.Write(referenceName);

/*
* Output:
*
* Iceland Krona
*/
Minor Units

A currency may also have a number of digits as decimals. The method GetMinorUnits returns that number, if applicable and available.

Example
using BenBurgers.InternationalStandards.Iso.Iso4217;

const Iso4217Code Value = Iso4217Code.JamaicanDollar;
var minorUnits = Value.GetMinorUnits(); // 2
Console.Write(minorUnits!.ToString());

/*
* Output:
*
* 2
*/
From text

The methods ToIso4217 and TryToIso4217 may be called on a string to convert a three-letter text to the ISO 4217 code.

Example
using BenBurgers.InternationalStandards.Iso.Iso4217;

const string Value = "JPY";
var code = Value.ToIso4217(); // Iso4217Code.Yen;
Console.Write(code.ToString());

/*
* Output:
*
* Yen
*/

Using TryToIso4217:

Example
using BenBurgers.InternationalStandards.Iso.Iso4217;

const string Value = "AAA";
if (Value.TryToIso4217(out var code)) {
    Console.WriteLine("Valid");
    Console.WriteLine(code!.ToString());
} else {
    Console.Write("Invalid");
}

/*
* Output:
*
* Invalid
*/

Comparers

All ISO codes have comparers. These can be found in the namespaces.

  • BenBurgers.InternationalStandards.Iso.Iso3166.Comparers
  • BenBurgers.InternationalStandards.Iso.Iso4217.Comparers
  • BenBurgers.InternationalStandards.Iso.Iso639.Comparers

A useful application could be in a SortedDictionary<...> with the ISO code as its items.

ISO 8601 date and time

The ISO 8601 standard describes how dates and times (or a combination thereof) are formatted.

The BenBurgers.InternationalStandards.Iso.Iso8601 namespace contains the following value types:

  • Iso8601CalendarDate
  • Iso8601OrdinalDate
  • Iso8601Time
  • Iso8601DateTime

Please review the official ISO 8601 standard for more information. This is the only authority that maintains the standard.

The value types support conversion from and to the .NET value types for times and dates by means of explicit casting or the methods provided.

The ToString and (static) Parse/TryParse methods provide ways to print or read the formatted values.

ISO 8601 Calendar Date

An ISO 8601 Calendar Date may have the following format: 2023-02-02 (yyyy-MM-dd). From the least significant up to the most significant component, components may be omitted, such as 2023-02 and 2023. The year is the only required component.

ISO 8601 Ordinal Date

An ISO 8601 Ordinal Date may have the following format: 2023-10 (yyyy-DDD). In this case the latter component is the day of the year, rather than month and day of month.

ISO 8601 Time

An ISO 8601 Time may have the following format: 23:10:05,0123+02:00 (HH:mm:ss,ssss+HH:mm). It is comprised of an hour, minute, second, fraction and UTC offset to indicate the time zone. As with the date, the least significant components may be omitted in order. The time zone may be included or omitted in any case. A special case of the time zone is the letter Z instead of +02:00 or -03:30. The Z indicates the UTC time and is used instead of +00:00.

ISO 8601 Date and Time

The ISO 8601 Date and Time combination combines the Date and Time components as described above. If both are specified, they will be separated by the letter T; e.g. 2023-02-02T23:10:05,0123+02:00.

Product Compatible and additional computed target framework versions.
.NET net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net6.0

    • No dependencies.
  • net7.0

    • No dependencies.

NuGet packages (3)

Showing the top 3 NuGet packages that depend on BenBurgers.InternationalStandards.Iso:

Package Downloads
BenBurgers.InternationalStandards.Iso.Json

JSON features for international standards as adopted by the International Organization for Standardization (ISO). This may include country codes, language codes and more.

BenBurgers.InternationalStandards.Iso.IO

Input/Output for international standards as adopted by the International Organization for Standardization (ISO). This may include country codes, language codes and more.

BenBurgers.InternationalStandards.Iso.EFCore

Entity Framework Core (SQL Server) features for international standards as adopted by the International Organization for Standardization (ISO). This may include country codes, language codes, currency codes and more.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
0.5.0 287 12/5/2023
0.4.0 540 1/3/2023
0.3.0 761 11/15/2022
0.2.0 515 11/9/2022
0.1.0 456 11/4/2022

Version 0.4.0
- Added Entity Framework Core features for value converters and model builders.
- ISO 3166: Breaking change; Iso3166AlphaMode moved from JSON package to main package.
- ISO 3166: Country codes are now generated from the data from the ISO 3166 Maintenance Agency (Online Browsing Platform), some field names may have changed. Properties "Independent" and official full names and short names in some languages added.
- ISO 639, 3166, 4217: Comparers added.
- ISO 639, 3166, 4217: Added ToModel method for retrieving the full model of an ISO code.
- ISO 639, 3166, 4217: Added TryTo[ISO] method for attempting to convert a string to its ISO code equivalent, without throwing an exception if it fails.
- ISO 8601: Added ISO 8601 date and time value types, including EFCore and JSON converters.
- If .NET 6.0 use official .NET 6.0 packages, if .NET 7.0 use official .NET 7.0 packages.
Version 0.3.0
- ISO 639: Fixed bug; if an unassigned Part of ISO 639 was requested, an exception was thrown that said it was deprecated.
- ISO 639: Implemented stub for conversion from string to ISO 639 code.
- ISO 3166: Improved documentation.
- ISO 4217: Added ISO 4217 currency codes.
- ISO 4217/IO: Added ISO 4217 Input/Output for importing currency codes from authority.
- ISO 4217/JSON: Added ISO 4217 (de)serialization.
Version 0.2.0
- ISO 639: Added ISO 639 language codes.
- ISO 639/IO: Added ISO 639 Input/Output for importing Code Tables from authority.
- ISO 639/JSON: Added ISO 639 (de)serialization.
- ISO 3166/JSON: Support for reading (in addition to writing) ISO 3166 numeric code as string.
- Added support for .NET 7.0 .
Version 0.1.0
- ISO 3166: Added ISO 3166 country codes.
- ISO 3166/JSON: Added ISO 3166 (de)serialization.