Docs, MIT, initial prerelease

This commit is contained in:
femsci 2023-12-24 15:14:17 +01:00
parent d590c7b8fa
commit 134f74d95d
Signed by: femsci
GPG key ID: 08F7911F0E650C67
5 changed files with 183 additions and 7 deletions

22
LICENSE.txt Normal file
View file

@ -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.

View file

@ -1,3 +1,57 @@
# Nyanbyte.Countries # 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);
```

View file

@ -1,5 +1,8 @@
namespace Nyanbyte.Countries; namespace Nyanbyte.Countries;
/// <summary>
/// Represents a country with various properties and methods to work with country data.
/// </summary>
public readonly partial struct Country public readonly partial struct Country
{ {
internal Country(CountryCode code, string officialName, string customaryName, int? phone, string? currencyCode, int? currencyNumeric, string capital, string tld) 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; CcTld = tld;
} }
/// <summary>
/// Retrieves a country based on its country code.
/// </summary>
/// <param name="code">The ISO 3166-1 alpha-2 country code enum.</param>
/// <returns>The retrieved country object.</returns>
public static Country GetFromCode(CountryCode code) public static Country GetFromCode(CountryCode code)
{ {
return _countries[code]; return _countries[code];
} }
/// <summary>
/// Retrieves a country based on its official or customary name.
/// </summary>
/// <param name="name">The name of the country.</param>
/// <returns>The retrieved country object.</returns>
public static Country? GetFromName(string name) public static Country? GetFromName(string name)
{ {
name = name.Trim(); name = name.Trim();
return _countries.SingleOrDefault(s => s.Value.OfficialName.Equals(name, StringComparison.OrdinalIgnoreCase) || s.Value.CustomaryName.Equals(name, StringComparison.OrdinalIgnoreCase)).Value; return _countries.SingleOrDefault(s => s.Value.OfficialName.Equals(name, StringComparison.OrdinalIgnoreCase) || s.Value.CustomaryName.Equals(name, StringComparison.OrdinalIgnoreCase)).Value;
} }
/// <summary>
/// Retrieves countries that use a specific currency code.
/// </summary>
/// <param name="code">The ISO 4217 3-letter currency code.</param>
/// <returns>A collection of countries.</returns>
public static IEnumerable<Country> GetByCurrency(string code) public static IEnumerable<Country> GetByCurrency(string code)
{ {
code = code.ToUpperInvariant(); code = code.ToUpperInvariant();
return _countries.Where(s => s.Value.CurrencyCode == code).Select(s => s.Value).AsEnumerable(); return _countries.Where(s => s.Value.CurrencyCode == code).Select(s => s.Value).AsEnumerable();
} }
/// <summary>
/// Retrieves countries that use a specific currency numeric code.
/// </summary>
/// <param name="code">The ISO 4217 numeric currency code.</param>
/// <returns>A collection of countries.</returns>
public static IEnumerable<Country> GetByCurrency(int code) public static IEnumerable<Country> GetByCurrency(int code)
{ {
return _countries.Where(s => s.Value.CurrencyCodeNumeric == code).Select(s => s.Value).AsEnumerable(); return _countries.Where(s => s.Value.CurrencyCodeNumeric == code).Select(s => s.Value).AsEnumerable();
} }
/// <summary>
/// Retrieves a country based on its country calling code.
/// </summary>
/// <param name="code">The ITU country calling code code.</param>
/// <returns>The retrieved country object.</returns>
public static Country? GetFromCallingCode(int code) public static Country? GetFromCallingCode(int code)
{ {
return _countries.SingleOrDefault(s => s.Value.CallingCode == code).Value; return _countries.SingleOrDefault(s => s.Value.CallingCode == code).Value;
} }
/// <summary>
/// Retrieves a country based on its country code top-level domain (ccTLD).
/// </summary>
/// <param name="ccTld">The top-level domain (ccTLD).</param>
/// <returns>The retrieved country object.</returns>
public static Country? GetFromTld(string ccTld) public static Country? GetFromTld(string ccTld)
{ {
ccTld = ccTld.Trim(); ccTld = ccTld.Trim();
@ -52,16 +85,54 @@ public readonly partial struct Country
return _countries.SingleOrDefault(s => s.Value.CcTld == ccTld).Value; return _countries.SingleOrDefault(s => s.Value.CcTld == ccTld).Value;
} }
/// <summary>
/// Retrieves all countries.
/// </summary>
/// <returns>A collection of all countries.</returns>
public static ICollection<Country> GetAll() => _countries.Select(c => c.Value).ToArray(); public static ICollection<Country> GetAll() => _countries.Select(c => c.Value).ToArray();
/// <summary>
/// Gets the country code enum (ISO 3166-1 alpha-2).
/// </summary>
public readonly CountryCode Code { get; private init; } public readonly CountryCode Code { get; private init; }
/// <summary>
/// Gets the ISO 3166-1 numeric code of the country.
/// </summary>
public readonly int IsoNumeric => (int)Code; public readonly int IsoNumeric => (int)Code;
/// <summary>
/// Gets the official name of the country.
/// </summary>
public readonly string OfficialName { get; private init; } public readonly string OfficialName { get; private init; }
/// <summary>
/// Gets the customary name of the country.
/// </summary>
public readonly string CustomaryName { get; private init; } public readonly string CustomaryName { get; private init; }
/// <summary>
/// Gets the ITU country calling code of the country.
/// </summary>
public readonly int? CallingCode { get; private init; } public readonly int? CallingCode { get; private init; }
//ISO 4217 currency code
/// <summary>
/// Gets the ISO 4217 currency code of the country.
/// </summary>
public readonly string? CurrencyCode { get; private init; } public readonly string? CurrencyCode { get; private init; }
/// <summary>
/// Gets the ISO 4217 numeric currency code of the country.
/// </summary>
public readonly int? CurrencyCodeNumeric { get; private init; } public readonly int? CurrencyCodeNumeric { get; private init; }
/// <summary>
/// Gets the capital city name of the country.
/// </summary>
public readonly string Capital { get; private init; } public readonly string Capital { get; private init; }
/// <summary>
/// Gets the top-level domain (TLD) of the country.
/// </summary>
public readonly string CcTld { get; private init; } public readonly string CcTld { get; private init; }
} }

View file

@ -1,5 +1,8 @@
namespace Nyanbyte.Countries; namespace Nyanbyte.Countries;
/// <summary>
/// An enum that represents ISO 3166-1 alpha-2 country codes and their corresponding numeric values.
/// </summary>
public enum CountryCode : short public enum CountryCode : short
{ {
AF = 004, AF = 004,
@ -255,6 +258,12 @@ public enum CountryCode : short
public static class CountryCodeUtils public static class CountryCodeUtils
{ {
/// <summary>
/// Retrieves the corresponding Country object based on the enum value.
/// </summary>
/// <returns>
/// The static Country object according to the enum value.
/// </returns>
public static Country GetCountry(this CountryCode code) public static Country GetCountry(this CountryCode code)
{ {
return Country._countries[code]; return Country._countries[code];

View file

@ -1,9 +1,29 @@
<Project Sdk="Microsoft.NET.Sdk"> <Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup> <PropertyGroup>
<TargetFramework>net7.0</TargetFramework> <TargetFramework>net8.0</TargetFramework>
<LangVersion>10.0</LangVersion>
<ImplicitUsings>enable</ImplicitUsings> <ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable> <Nullable>enable</Nullable>
<PackageId>Nyanbyte.Countries</PackageId>
<Version>0.0.1</Version>
<Authors>femsci</Authors>
<Company>Nyanbyte</Company>
<Product>Countries</Product>
<Description>A small library for static country data, including official and shorthand
names,
dialing country codes, currencies and TLDs</Description>
<PackageTags>dataset;countries;country codes</PackageTags>
<PackageProjectUrl>https://git.femboy.science/Nyanbyte/Countries</PackageProjectUrl>
<RepositoryType>git</RepositoryType>
<RepositoryUrl>https://git.femboy.science/Nyanbyte/Countries</RepositoryUrl>
<Copyright>Copyright © Nyanbyte P.S.A. 2023</Copyright>
<PackageLicenseExpression>MIT</PackageLicenseExpression>
<PackageReadmeFile>README.md</PackageReadmeFile>
</PropertyGroup> </PropertyGroup>
<ItemGroup>
<None Include="../../README.md" Pack="true" PackagePath="" />
</ItemGroup>
</Project> </Project>