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