CkCountry

Job: turn any way of writing a country into the one form you need — the two-letter code, the three-letter code, or the English name — and answer the yes-or-no questions about it: is this a country, is it one of ours, are these two the same.

People write countries in many ways: "US", "usa", "United States", "U.S.A.", "UK". CkCountry understands the ISO 3166-1 codes, the official English names, and the everyday spellings — in any casing, with or without dots, spaces and accents. It never guesses: a misspelled country is rejected rather than matched to the nearest name, because "Austria" and "Australia" are one bad guess apart.

Quick look

using SafeCoder.CommonKit;

CkCountry.Alpha2("United States");   // -> "US"
CkCountry.Alpha2("U.S.A.");          // -> "US"
CkCountry.Alpha3("uk");              // -> "GBR"
CkCountry.Name("de");                // -> "Germany"
CkCountry.Name("banana");            // -> ""  (not a country — rejected)
CkCountry.IsCountry("Germny");       // -> false
CkCountry.InCountries("U.S.A.", "us", "ca", "mx");   // -> true
CkCountry.SameCountry("UK", "Great Britain");        // -> true
CkCountry.Flag("U.S.A.");        // -> 🇺🇸
CkCountry.Explain("Germny");     // -> "not a recognised country or code"

Methods

Alpha2

The two-letter code.

string Alpha2(
    string? input = null,
    string? fallback = null,
    bool throwIfInvalid = CkSettings.DefaultThrowIfInvalid
)

Parameter	Type	Default	What it does
input	string?	null	The raw country value: a code or a name in any everyday spelling — "us", "USA", "United States", "U.S.A.".
fallback	string?	null	Backup value used when the result would be empty. It goes through the same cleaning and checks as input; a fallback that is itself rejected answers "". Null or empty means no fallback.
throwIfInvalid	bool	CkSettings.DefaultThrowIfInvalid (false)	Pass true to throw a CkCountryException that says why, instead of answering "", when neither the value nor the fallback can be used.

Returns

When	Default	With throwIfInvalid: true
The value (or the fallback) is a recognised country	The upper-case alpha-2 code: "US"	The upper-case alpha-2 code: "US"
Rejected: missing, oversized, a missing-data marker, or not a recognised country or code	Empty string	Throws CkCountryException — carries Input, Expected and Reason

Matching is exact after tidying — a misspelling is rejected, never guessed.

The ISO alpha-2 code ("US", "GB", "DE") — the two letters that domains, locales and most APIs key on. Give it a code or a name in any everyday spelling; bad input answers "".

CkCountry.Alpha2("United States");   // -> "US"
CkCountry.Alpha2("usa");             // -> "US"   (alpha-3 in, alpha-2 out)
CkCountry.Alpha2("UK");              // -> "GB"   (everyday spelling)
CkCountry.Alpha2("Burma");           // -> "MM"   (older name, still understood)
CkCountry.Alpha2("côte d'ivoire");   // -> "CI"   (accents are fine)
CkCountry.Alpha2("Germny");          // -> ""     (misspelled — never guessed)

Alpha3

The three-letter code.

string Alpha3(
    string? input = null,
    string? fallback = null,
    bool throwIfInvalid = CkSettings.DefaultThrowIfInvalid
)

Parameter	Type	Default	What it does
input	string?	null	The raw country value: a code or a name in any everyday spelling — "us", "USA", "United States", "U.S.A.".
fallback	string?	null	Backup value used when the result would be empty. It goes through the same cleaning and checks as input; a fallback that is itself rejected answers "". Null or empty means no fallback.
throwIfInvalid	bool	CkSettings.DefaultThrowIfInvalid (false)	Pass true to throw a CkCountryException that says why, instead of answering "", when neither the value nor the fallback can be used.

Returns

When	Default	With throwIfInvalid: true
The value (or the fallback) is a recognised country	The upper-case alpha-3 code: "USA"	The upper-case alpha-3 code: "USA"
Rejected: missing, oversized, a missing-data marker, or not a recognised country or code	Empty string	Throws CkCountryException — carries Input, Expected and Reason

Matching is exact after tidying — never fuzzy.

The ISO alpha-3 code ("USA", "GBR", "DEU") — the three letters customs and some government systems use. Same inputs, same rules.

CkCountry.Alpha3("US");              // -> "USA"
CkCountry.Alpha3("Czech Republic");  // -> "CZE"

Name

The English name.

string Name(
    string? input = null,
    string? fallback = null,
    bool throwIfInvalid = CkSettings.DefaultThrowIfInvalid
)

Parameter	Type	Default	What it does
input	string?	null	The raw country value: a code or a name in any everyday spelling — "us", "USA", "United States", "U.S.A.".
fallback	string?	null	Backup value used when the result would be empty. It goes through the same cleaning and checks as input; a fallback that is itself rejected answers "". Null or empty means no fallback.
throwIfInvalid	bool	CkSettings.DefaultThrowIfInvalid (false)	Pass true to throw a CkCountryException that says why, instead of answering "", when neither the value nor the fallback can be used.

Returns

When	Default	With throwIfInvalid: true
The value (or the fallback) is a recognised country	The English name: "United States"	The English name: "United States"
Rejected: missing, oversized, a missing-data marker, or not a recognised country or code	Empty string	Throws CkCountryException — carries Input, Expected and Reason

The common everyday name, not the ceremonial ISO long form.

The everyday English name, tidy and correctly cased.

CkCountry.Name("US");                // -> "United States"
CkCountry.Name("GBR");               // -> "United Kingdom"
CkCountry.Name("czech republic");    // -> "Czechia"  (the current short name)

IsCountry

Is this a country at all?

bool IsCountry(
    string? input = null,
    bool throwIfInvalid = CkSettings.DefaultThrowIfInvalid
)

Parameter	Type	Default	What it does
input	string?	null	The raw country value: a code or a name in any everyday spelling.
throwIfInvalid	bool	CkSettings.DefaultThrowIfInvalid (false)	Pass true to throw a CkCountryException that says why, instead of answering false, when the value is not a recognised country.

Returns

When	Default	With throwIfInvalid: true
The value is a recognised country, under the same rules as Alpha2	true	true
Rejected: missing, a missing-data marker, ambiguous, or not a recognised country or code	false	Throws CkCountryException — carries Input, Expected and Reason

The yes-or-no form of the readers, for validation code. When the value is going to be stored, read it with Alpha2 instead and check for "": that answers the same question and hands you the code.

CkCountry.IsCountry("U.S.A.");   // -> true
CkCountry.IsCountry("UK");       // -> true   (aliases count)
CkCountry.IsCountry("Germny");   // -> false  (never fuzzy)
CkCountry.IsCountry("Congo");    // -> false  (ambiguous)

IsAlpha2

Is it written as the two-letter code?

bool IsAlpha2(
    string? input = null,
    bool throwIfInvalid = CkSettings.DefaultThrowIfInvalid
)

Parameter	Type	Default	What it does
input	string?	null	The raw value.
throwIfInvalid	bool	CkSettings.DefaultThrowIfInvalid (false)	Pass true to throw a CkCountryException that says why, instead of answering false, when the value is not an alpha-2 code.

Returns

When	Default	With throwIfInvalid: true
The cleaned value is exactly an assigned ISO 3166-1 alpha-2 code — "US", "ro", " GB "	true	true
A country, but not written as its alpha-2 code — "USA", "United States", "UK", "U.S."	false	Throws — the reason says it is a country in another form
Not a recognised country at all	false	Throws CkCountryException — carries Input, Expected and Reason

A shape check for a column or an API field that must carry the code and nothing else. Casing and surrounding whitespace are forgiven, as Alpha2 forgives them, but a name, an alias or a dotted spelling is not the code: "UK" answers false, because the United Kingdom's code is "GB". To accept any way of writing a country and store the code, read the value with Alpha2 instead.

CkCountry.IsAlpha2("us");              // -> true
CkCountry.IsAlpha2("USA");             // -> false  (that is the alpha-3 code)
CkCountry.IsAlpha2("United States");   // -> false  (a name — read it with Alpha2)
CkCountry.IsAlpha2("XX");              // -> false  (two letters, but unassigned)

IsAlpha3

Is it written as the three-letter code?

bool IsAlpha3(
    string? input = null,
    bool throwIfInvalid = CkSettings.DefaultThrowIfInvalid
)

Parameter	Type	Default	What it does
input	string?	null	The raw value.
throwIfInvalid	bool	CkSettings.DefaultThrowIfInvalid (false)	Pass true to throw a CkCountryException that says why, instead of answering false, when the value is not an alpha-3 code.

Returns

When	Default	With throwIfInvalid: true
The cleaned value is exactly an assigned ISO 3166-1 alpha-3 code — "USA", "rou", " GBR "	true	true
A country, but not written as its alpha-3 code — "US", "United States", "UAE"	false	Throws — the reason says it is a country in another form
Not a recognised country at all	false	Throws CkCountryException — carries Input, Expected and Reason

The three-letter twin of IsAlpha2, with the same rules: "UAE" answers false, because the United Arab Emirates' code is "ARE".

CkCountry.IsAlpha3("rou");   // -> true
CkCountry.IsAlpha3("RO");    // -> false  (that is the alpha-2 code)
CkCountry.IsAlpha3("UAE");   // -> false  (an alias — the code is ARE)

InCountries

Is it one of these countries?

bool InCountries(
    string? input = null,
    params IEnumerable<string?> allowed
)

Parameter	Type	Default	What it does
input	string?	null	The raw country value: a code or a name in any everyday spelling.
allowed	params IEnumerable<string?>	—	The countries to accept, each in any form. Entries that are not recognised are skipped.

Returns

When	You get
The value is a recognised country and an entry names the same one	true
It is not recognised, no entry matches, or the list is empty	false — an answer, not a failure; it never throws

The shipping-zone, sanctions-list and "countries we serve" check. The value and every entry are read the way Alpha2 reads them, so the list may mix codes, names and everyday spellings, and the value need not match any entry letter for letter. The list is yours to maintain: the library ships no region lists such as EU, EEA or Schengen, whose membership changes with legal consequences. A params list must be the last parameter, so there is no throwIfInvalid; call Alpha2 with it first when you need the exception for an unrecognised value.

CkCountry.InCountries("U.S.A.", "us", "Canada", "MEX");   // -> true
CkCountry.InCountries("UK", "Great Britain");             // -> true
CkCountry.InCountries("Germany", "us", "Canada", "MEX");  // -> false
CkCountry.InCountries("junk", "us");                      // -> false  (unrecognised matches nothing)

SameCountry

Do these two name the same country?

bool SameCountry(
    string? a = null,
    string? b = null,
    bool throwIfInvalid = CkSettings.DefaultThrowIfInvalid
)

Parameter	Type	Default	What it does
a	string?	null	The first value.
b	string?	null	The second value.
throwIfInvalid	bool	CkSettings.DefaultThrowIfInvalid (false)	Pass true to throw a CkCountryException that says which value is not a recognised country and why, instead of answering false.

Returns

When	Default	With throwIfInvalid: true
Both values are recognised countries with the same code	true	true
Both are recognised, but different countries	false	false — different is an answer, not an error
Rejected: either value is not a recognised country	false	Throws CkCountryException — carries Input, Expected and Reason

For "billing country equals shipping country" and for matching records across systems that spell countries differently. Unlike CkText.SameText, two values that are not countries are never "the same" — two rejected values are two unknowns, not one country.

CkCountry.SameCountry("UK", "Great Britain");        // -> true
CkCountry.SameCountry("usa", "United States");       // -> true
CkCountry.SameCountry("Austria", "Australia");       // -> false
CkCountry.SameCountry("junk", "junk");               // -> false  (two unknowns)

Flag

The flag, as text.

string Flag(
    string? input = null,
    string? fallback = null,
    bool throwIfInvalid = CkSettings.DefaultThrowIfInvalid
)

Parameter	Type	Default	What it does
input	string?	null	The raw country value: a code or a name in any everyday spelling.
fallback	string?	null	A spare value, processed the same way.
throwIfInvalid	bool	CkSettings.DefaultThrowIfInvalid (false)	Pass true to throw a CkCountryException that says why, instead of answering "", when neither the value nor the fallback can be used.

Returns

When	Default	With throwIfInvalid: true
A recognised country	The flag emoji: "Romania" is 🇷🇴	The flag
Rejected: not a recognised country	""	Throws CkCountryException — carries Input, Expected and Reason

No image and no table: the two letters of the alpha-2 code become the two regional-indicator characters every modern font draws as that flag, so the result is text and travels anywhere text does.

CkCountry.Flag("U.S.A.");   // -> 🇺🇸
CkCountry.Flag("UK");       // -> 🇬🇧

Explain

Why not — in words, without an exception.

string Explain(
    string? input = null
)

Parameter	Type	Default	What it does
input	string?	null	The raw country value.

Returns

When	You get
The value passes the reader	""
It does not	The reason, the same words the exception would carry — an answer, not a failure; it never throws

The form-friendly twin of throwIfInvalid: the message to show beside the field, without a try and catch. Every class with a reader has one, on the reader's own rules, so the reason is exactly what the reader would say.

CkCountry.Explain("Germny");   // -> "not a recognised country or code"
CkCountry.Explain("N/A");      // -> "a missing-data marker, not a country"

The fallback

The three readers — Alpha2, Alpha3, Name — take a fallback: a spare value used when the input is rejected. The fallback goes through the exact same cleaning and checking; a bad fallback answers "" too. The validators have no fallback: false is their answer.

CkCountry.Alpha2(
    input: form["country"],
    fallback: "US"
);   // -> the parsed country, or "US" when the field is empty or unusable

Good to know

• Ambiguous names are rejected, not guessed. "Congo" alone answers "" — there are two Congos; say which one.
• A digit means it is not a country. Punctuation and spaces drop before matching, so U.S.A. and côte d'ivoire read; a digit does not drop — no country's name, alias or code has one — so 12TZ34, or a timestamp ending in …T23:59:59Z, is refused instead of reading as Tanzania.
• "N/A" answers "". It is treated as a missing-data marker, never matched to Namibia.
• Matching is exact after tidying. Casing, dots, spaces and accents are ignored, but there is no fuzzy matching — a typo answers "" so you can catch it, instead of silently becoming the wrong country.
• IsAlpha2 judges the shape, Alpha2 reads any form. IsAlpha2("UK") is false — "UK" is an alias, the assigned code is "GB" — while Alpha2("UK") is "GB". Use the validator where a field must already hold the code; use the reader everywhere else.
• No built-in region lists. There is no IsEu or IsSchengen: membership changes, with legal consequences, so the list stays in your application and goes through InCountries.
• InCountries takes no throwIfInvalid. A params list must be the last parameter; call Alpha2 with the flag first when you need the exception.
• Non-empty in, empty out means rejected. That is the standard CommonKit signal for the readers — check for "" where it matters. The validators answer false instead.

If you want errors instead

Pass throwIfInvalid: true and a value that cannot be used raises a CkCountryException (from SafeCoder.CommonKit.Exceptions) instead of answering "" — or false, from IsCountry, IsAlpha2, IsAlpha3 and SameCountry. The exception carries the Input and a short Reason, flattened into a one-line message. InCountries never takes the parameter: false is its answer.

CkCountry.Alpha2(
    input: "Germny",
    throwIfInvalid: true
);   // throws CkCountryException — the message says why