Docs, MIT, initial prerelease

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

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);
+```

src/Nyanbyte.Countries/Country.cs

@@ -1,5 +1,8 @@
 namespace Nyanbyte.Countries;
 
+/// <summary>
+/// Represents a country with various properties and methods to work with country data.
+/// </summary>
 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;
     }
 
+    /// <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)
     {
         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)
     {
         name = name.Trim();
         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)
     {
         code = code.ToUpperInvariant();
         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)
     {
         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)
     {
         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)
     {
         ccTld = ccTld.Trim();
@@ -52,16 +85,54 @@ public readonly partial struct Country
         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();
 
+    /// <summary>
+    /// Gets the country code enum (ISO 3166-1 alpha-2).
+    /// </summary>
     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;
+
+    /// <summary>
+    /// Gets the official name of the country.
+    /// </summary>
     public readonly string OfficialName { get; private init; }
+
+    /// <summary>
+    /// Gets the customary name of the country.
+    /// </summary>
     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; }
-    //ISO 4217 currency code
+
+    /// <summary>
+    /// Gets the ISO 4217 currency code of the country.
+    /// </summary>
     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; }
+
+    /// <summary>
+    /// Gets the capital city name of the country.
+    /// </summary>
     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; }
 }

src/Nyanbyte.Countries/CountryCode.cs

@@ -1,5 +1,8 @@
 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
 {
     AF = 004,
@@ -255,6 +258,12 @@ public enum CountryCode : short
 
 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)
     {
         return Country._countries[code];

src/Nyanbyte.Countries/Nyanbyte.Countries.csproj

@@ -1,9 +1,29 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
     <PropertyGroup>
-    <TargetFramework>net7.0</TargetFramework>
+        <TargetFramework>net8.0</TargetFramework>
+        <LangVersion>10.0</LangVersion>
         <ImplicitUsings>enable</ImplicitUsings>
         <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>
 
+    <ItemGroup>
+        <None Include="../../README.md" Pack="true" PackagePath="" />
+    </ItemGroup>
+
 </Project>