From 134f74d95db64962f11cb5dfdb94f5ff4c101ef4 Mon Sep 17 00:00:00 2001 From: femsci Date: Sun, 24 Dec 2023 15:14:17 +0100 Subject: [PATCH] Docs, MIT, initial prerelease --- LICENSE.txt | 22 ++++++ README.md | 56 +++++++++++++- src/Nyanbyte.Countries/Country.cs | 73 ++++++++++++++++++- src/Nyanbyte.Countries/CountryCode.cs | 9 +++ .../Nyanbyte.Countries.csproj | 30 ++++++-- 5 files changed, 183 insertions(+), 7 deletions(-) create mode 100644 LICENSE.txt diff --git a/LICENSE.txt b/LICENSE.txt new file mode 100644 index 0000000..7f72107 --- /dev/null +++ b/LICENSE.txt @@ -0,0 +1,22 @@ +MIT License + +Copyright (c) 2023 Nyanbyte P.S.A. + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + diff --git a/README.md b/README.md index 1182f05..67f151c 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,57 @@ # Nyanbyte.Countries -A .NET library for country data, including ISO Codes, languages, and other data associated with countries +A .NET library for country data, including ISO Codes, currencies, and other data associated with countries. + +## Usage + +### Fixed countries by ISO 3166-1 alpha2 code enums + +```csharp +using Nyanbyte.Countries; + +Country pl = CountryCodes.PL.GetCountry(); + +// use the object + +Console.WriteLine(pl.OfficialName == "Poland"); +``` + +or + +```csharp +using Nyanbyte.Countries; + +Country pl = Country.GetFromCode(CountryCodes.PL); + +// use the object + +Console.WriteLine(pl.OfficialName == "Poland"); +``` + +### Querying by data + +The methods: + +- `GetFromName` +- `GetByCurrency(string)` +- `GetByCurrency(int)` +- `GetFromCallingCode` +- `GetFromTld` + +do not guarantee results due to potential invalid input. +Therefore validation is required. + +```csharp +using Nyanbyte.Countries; + +Country? country = Country.GetFromCallingCode(48); + +if(country is null) +{ + //handle invalid result + return; +} + +// use the object otherwise +Console.WriteLine(pl.OfficialName); +``` diff --git a/src/Nyanbyte.Countries/Country.cs b/src/Nyanbyte.Countries/Country.cs index 3af9841..c0bbeb2 100644 --- a/src/Nyanbyte.Countries/Country.cs +++ b/src/Nyanbyte.Countries/Country.cs @@ -1,5 +1,8 @@ namespace Nyanbyte.Countries; +/// +/// Represents a country with various properties and methods to work with country data. +/// public readonly partial struct Country { internal Country(CountryCode code, string officialName, string customaryName, int? phone, string? currencyCode, int? currencyNumeric, string capital, string tld) @@ -14,33 +17,63 @@ public readonly partial struct Country CcTld = tld; } + /// + /// Retrieves a country based on its country code. + /// + /// The ISO 3166-1 alpha-2 country code enum. + /// The retrieved country object. public static Country GetFromCode(CountryCode code) { return _countries[code]; } + /// + /// Retrieves a country based on its official or customary name. + /// + /// The name of the country. + /// The retrieved country object. public static Country? GetFromName(string name) { name = name.Trim(); return _countries.SingleOrDefault(s => s.Value.OfficialName.Equals(name, StringComparison.OrdinalIgnoreCase) || s.Value.CustomaryName.Equals(name, StringComparison.OrdinalIgnoreCase)).Value; } + /// + /// Retrieves countries that use a specific currency code. + /// + /// The ISO 4217 3-letter currency code. + /// A collection of countries. public static IEnumerable GetByCurrency(string code) { code = code.ToUpperInvariant(); return _countries.Where(s => s.Value.CurrencyCode == code).Select(s => s.Value).AsEnumerable(); } + /// + /// Retrieves countries that use a specific currency numeric code. + /// + /// The ISO 4217 numeric currency code. + /// A collection of countries. public static IEnumerable GetByCurrency(int code) { return _countries.Where(s => s.Value.CurrencyCodeNumeric == code).Select(s => s.Value).AsEnumerable(); } + /// + /// Retrieves a country based on its country calling code. + /// + /// The ITU country calling code code. + /// The retrieved country object. public static Country? GetFromCallingCode(int code) { return _countries.SingleOrDefault(s => s.Value.CallingCode == code).Value; } + /// + /// Retrieves a country based on its country code top-level domain (ccTLD). + /// + /// The top-level domain (ccTLD). + /// The retrieved country object. public static Country? GetFromTld(string ccTld) { ccTld = ccTld.Trim(); @@ -52,16 +85,54 @@ public readonly partial struct Country return _countries.SingleOrDefault(s => s.Value.CcTld == ccTld).Value; } + /// + /// Retrieves all countries. + /// + /// A collection of all countries. public static ICollection GetAll() => _countries.Select(c => c.Value).ToArray(); + /// + /// Gets the country code enum (ISO 3166-1 alpha-2). + /// public readonly CountryCode Code { get; private init; } + + /// + /// Gets the ISO 3166-1 numeric code of the country. + /// public readonly int IsoNumeric => (int)Code; + + /// + /// Gets the official name of the country. + /// public readonly string OfficialName { get; private init; } + + /// + /// Gets the customary name of the country. + /// public readonly string CustomaryName { get; private init; } + + /// + /// Gets the ITU country calling code of the country. + /// public readonly int? CallingCode { get; private init; } - //ISO 4217 currency code + + /// + /// Gets the ISO 4217 currency code of the country. + /// public readonly string? CurrencyCode { get; private init; } + + /// + /// Gets the ISO 4217 numeric currency code of the country. + /// public readonly int? CurrencyCodeNumeric { get; private init; } + + /// + /// Gets the capital city name of the country. + /// public readonly string Capital { get; private init; } + + /// + /// Gets the top-level domain (TLD) of the country. + /// public readonly string CcTld { get; private init; } } diff --git a/src/Nyanbyte.Countries/CountryCode.cs b/src/Nyanbyte.Countries/CountryCode.cs index 331b0b1..541c9e8 100644 --- a/src/Nyanbyte.Countries/CountryCode.cs +++ b/src/Nyanbyte.Countries/CountryCode.cs @@ -1,5 +1,8 @@ namespace Nyanbyte.Countries; +/// +/// An enum that represents ISO 3166-1 alpha-2 country codes and their corresponding numeric values. +/// public enum CountryCode : short { AF = 004, @@ -255,6 +258,12 @@ public enum CountryCode : short public static class CountryCodeUtils { + /// + /// Retrieves the corresponding Country object based on the enum value. + /// + /// + /// The static Country object according to the enum value. + /// public static Country GetCountry(this CountryCode code) { return Country._countries[code]; diff --git a/src/Nyanbyte.Countries/Nyanbyte.Countries.csproj b/src/Nyanbyte.Countries/Nyanbyte.Countries.csproj index cfadb03..d0b6c1b 100644 --- a/src/Nyanbyte.Countries/Nyanbyte.Countries.csproj +++ b/src/Nyanbyte.Countries/Nyanbyte.Countries.csproj @@ -1,9 +1,29 @@ - - net7.0 - enable - enable - + + net8.0 + 10.0 + enable + enable + Nyanbyte.Countries + 0.0.1 + femsci + Nyanbyte + Countries + A small library for static country data, including official and shorthand + names, + dialing country codes, currencies and TLDs + dataset;countries;country codes + https://git.femboy.science/Nyanbyte/Countries + git + https://git.femboy.science/Nyanbyte/Countries + Copyright © Nyanbyte P.S.A. 2023 + MIT + README.md + + + + +