CkUS

Job: clean and check the identifiers American data carries — phone numbers, SSNs, ZIP codes, bank numbers, medical codes — and mask them safely for display.

International numbers live in CkIntl

CkUS is for US-shaped values only. International phone numbers (+49 …), IBANs and BIC codes live in CkIntl.

US records are full of numbers with rules: a phone number has a valid shape, a Social Security number has ranges that are never issued, a routing number carries a checksum. CkUS knows those rules. Every method strips markup and separators first, then checks the value the way the issuing body defines it. A value that fails answers "" (empty string) — non-empty in, empty out means rejected. The one exception: the …Mask methods are made for display and never return empty.

Quick look

using SafeCoder.CommonKit;

CkUS.Phone("1 (555) 234-5678");    // -> "+15552345678"
CkUS.Ssn("123 45 6789");           // -> "123-45-6789"
CkUS.Zip("2134");                  // -> "02134"  (lost leading zero restored)
CkUS.State("california");          // -> "CA"
CkUS.RoutingNumber("junk");        // -> ""  (rejected — check for empty)
CkUS.SsnMask("123-45-6789");       // -> "***-**-6789"  (masks never come back empty)
CkUS.IsSsn("123 45 6789");         // -> true
CkUS.InStates("california", "CA", "OR", "WA");   // -> true
CkUS.SamePhone("(415) 555-0142", "+14155550142");   // -> true
CkUS.InIcd10Ranges("F25.0", "F20-F29");             // -> true
CkUS.IsPoBox("PO Box 123");        // -> true
CkUS.Explain("911-234-5678");      // -> "the area code cannot be an N11 service code"

Some methods take small format enums from SafeCoder.CommonKit.Enums — PhoneFormatUS, SsnFormatUS, EinFormatUS, ZipFormatUS, StateFormatUS. A format parameter says which layout you accept in; an output parameter says which shape you want back. You'll see them in the examples below. (TinKindUS is different — it is Tin's answer.)

Methods

Phone

US phone numbers.

string Phone(
    string? input = null,
    PhoneFormatUS format = PhoneFormatUS.Loose,
    PhoneFormatUS output = PhoneFormatUS.Any,
    string? fallback = null,
    bool throwIfInvalid = CkSettings.DefaultThrowIfInvalid
)

Parameter	Type	Default	What it does
input	string?	null	The raw phone value.
format	PhoneFormatUS	PhoneFormatUS.Loose	The layout the input must match. Loose reads any mix of digits, separators, a leading +1 and a trailing extension; Any accepts only the four exact layouts.
output	PhoneFormatUS	PhoneFormatUS.Any	The shape to return. Any keeps a value that arrived in an exact layout unchanged and turns a loose one into E.164; pass PhoneFormatUS.E164 for the same canonical shape every time.
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 "".
throwIfInvalid	bool	CkSettings.DefaultThrowIfInvalid (false)	Pass true to throw a CkUSException 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 valid NANP number	The number re-shaped as output: "+15552345678" — the PhoneFormatUS enum picks the layout	The number re-shaped as output: "+15552345678" — the PhoneFormatUS enum picks the layout
Rejected: missing, oversized, malformed, or not a valid NANP number	Empty string	Throws CkUSException — carries Input, Expected and Reason

Extensions are dropped, not returned — keep them in a separate field.

Cleans and validates a NANP number (NANP = the North American Numbering Plan, the ten-digit system the US and Canada share). By default the input is read loosely — any mix of digits, dots, dashes, spaces and parentheses, a leading +1 or 1, and a trailing extension like x12 is dropped. The output parameter picks the shape you get back; its default, PhoneFormatUS.Any, keeps a value that arrived in one of the four exact layouts unchanged and turns a loosely typed one into E.164 (the international form: +, country code, then the digits, no spaces).

using SafeCoder.CommonKit.Enums;

CkUS.Phone("1 (555) 234-5678");    // -> "+15552345678"   (loose in, E.164 out)
CkUS.Phone("(555) 234-5678");      // -> "(555) 234-5678" (an exact layout is kept)
CkUS.Phone("555-234-5678 x12");    // -> "+15552345678"   (extension dropped)
CkUS.Phone(
    input: "555.234.5678",
    output: PhoneFormatUS.National
);                                 // -> "(555) 234-5678"
CkUS.Phone("555-211-5678");        // -> ""  (211 exchange — an N11 service code)

Ssn

The social security number.

string Ssn(
    string? input = null,
    SsnFormatUS format = SsnFormatUS.Any,
    SsnFormatUS output = SsnFormatUS.Dashed,
    string? fallback = null,
    bool throwIfInvalid = CkSettings.DefaultThrowIfInvalid
)

Parameter	Type	Default	What it does
input	string?	null	The raw value.
format	SsnFormatUS	SsnFormatUS.Any	The layout the input must match; Any accepts every supported layout (dashed, spaced or bare).
output	SsnFormatUS	SsnFormatUS.Dashed	The shape to return. Pass SsnFormatUS.Digits for storage, or Any to keep the layout the number arrived in.
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 "".
throwIfInvalid	bool	CkSettings.DefaultThrowIfInvalid (false)	Pass true to throw a CkUSException 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 valid SSN	The number re-shaped as output, dashed by default: "123-45-6789" — the SsnFormatUS enum picks the layout	The number re-shaped as output, dashed by default: "123-45-6789" — the SsnFormatUS enum picks the layout
Rejected: missing, oversized, malformed, or breaks the issuing rules	Empty string	Throws CkUSException — carries Input, Expected and Reason

Validation is structural only — it cannot tell whether the number was ever issued to anyone.

Validates a Social Security number in the dashed, spaced or bare layout, and applies the real issuing rules: the first three digits are never 000, 666 or 900–999, the middle two never 00, the last four never 0000. The output parameter defaults to SsnFormatUS.Dashed.

CkUS.Ssn("123456789");             // -> "123-45-6789"
CkUS.Ssn(
    input: "123-45-6789",
    output: SsnFormatUS.Digits
);                                 // -> "123456789"  (the storage shape)
CkUS.Ssn("666-12-3456");           // -> ""  (area 666 is never issued)

Itin

The tax number for people without an SSN.

string Itin(
    string? input = null,
    SsnFormatUS format = SsnFormatUS.Any,
    SsnFormatUS output = SsnFormatUS.Dashed,
    string? fallback = null,
    bool throwIfInvalid = CkSettings.DefaultThrowIfInvalid
)

Parameter	Type	Default	What it does
input	string?	null	The raw value.
format	SsnFormatUS	SsnFormatUS.Any	The layout the input must match; Any accepts every supported layout (dashed, spaced or bare).
output	SsnFormatUS	SsnFormatUS.Dashed	The shape to return. Pass SsnFormatUS.Digits for storage, or Any to keep the layout the number arrived in.
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 "".
throwIfInvalid	bool	CkSettings.DefaultThrowIfInvalid (false)	Pass true to throw a CkUSException 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 valid ITIN	The number re-shaped as output, dashed by default: "912-70-1234" — the SsnFormatUS enum picks the layout	The number re-shaped as output, dashed by default: "912-70-1234" — the SsnFormatUS enum picks the layout
Rejected: missing, oversized, malformed, or structurally invalid	Empty string	Throws CkUSException — carries Input, Expected and Reason

Deliberately the exact complement of Ssn — no value can pass both, which is how Tin tells them apart.

Validates an Individual Taxpayer Identification Number — the SSN-shaped number the IRS gives people who cannot get an SSN. Its first digit is always 9, and its middle two digits must fall in an IRS range. It is the exact complement of Ssn: no value can pass both. It takes the same SsnFormatUS layouts as Ssn and answers dashed by default.

CkUS.Itin("912701234");            // -> "912-70-1234"

Ein

The employer tax number.

string Ein(
    string? input = null,
    EinFormatUS format = EinFormatUS.Any,
    EinFormatUS output = EinFormatUS.Dashed,
    string? fallback = null,
    bool throwIfInvalid = CkSettings.DefaultThrowIfInvalid
)

Parameter	Type	Default	What it does
input	string?	null	The raw value.
format	EinFormatUS	EinFormatUS.Any	The layout the input must match; Any accepts both layouts (dashed or bare).
output	EinFormatUS	EinFormatUS.Dashed	The shape to return. Pass EinFormatUS.Digits for storage, or Any to keep the layout the number arrived in.
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 "".
throwIfInvalid	bool	CkSettings.DefaultThrowIfInvalid (false)	Pass true to throw a CkUSException 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 valid EIN	The number re-shaped as output, dashed by default: "12-3456789" — the EinFormatUS enum picks the layout	The number re-shaped as output, dashed by default: "12-3456789" — the EinFormatUS enum picks the layout
Rejected: missing, oversized, malformed, or a two-digit prefix the IRS never assigns	Empty string	Throws CkUSException — carries Input, Expected and Reason

An EIN has no check digit, so this cannot tell whether the number was actually issued.

Validates an Employer Identification Number (12-3456789) and rejects the two-digit prefixes the IRS has never assigned. EinFormatUS picks the layout.

CkUS.Ein("123456789");             // -> "12-3456789"

Tin

Which kind of tax number this is.

TinKindUS Tin(
    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 CkUSException that says why, instead of answering TinKindUS.Invalid, when the value is none of the three kinds.

Returns

When	Default	With throwIfInvalid: true
The value is a valid ITIN, SSN or EIN	The kind as a TinKindUS value: TinKindUS.Ein	The kind as a TinKindUS value: TinKindUS.Ein
Rejected: no kind accepts the value, a missing value included	TinKindUS.Invalid	Throws CkUSException — carries Input, Expected and Reason

This classifies shape only — it does not tell whether the number was ever issued.

Answers the question "which kind is this Tax ID?" — it returns a TinKindUS value (Itin, Ssn, Ein or Invalid), not a string.

CkUS.Tin("12-3456789");            // -> TinKindUS.Ein
CkUS.Tin("123456789");             // -> TinKindUS.Ssn  (bare nine digits read as an SSN)
CkUS.Tin("912-70-1234");           // -> TinKindUS.Itin

Zip

The postal code.

string Zip(
    string? input = null,
    ZipFormatUS format = ZipFormatUS.Any,
    bool padLeadingZeros = true,
    string? fallback = null,
    bool throwIfInvalid = CkSettings.DefaultThrowIfInvalid
)

Parameter	Type	Default	What it does
input	string?	null	The raw ZIP value.
format	ZipFormatUS	ZipFormatUS.Any	The layout the input must match; Any accepts every supported layout.
padLeadingZeros	bool	true	Restores leading zeros lost to a spreadsheet or an integer column: "2134" becomes "02134". It only ever touches a bare 3–4 or 7–8 digit group.
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 "".
throwIfInvalid	bool	CkSettings.DefaultThrowIfInvalid (false)	Pass true to throw a CkUSException 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 valid ZIP	The validated code — five digits, or ZIP+4 with the hyphen: "90210-1234" — the ZipFormatUS enum picks the layout accepted in	The validated code — five digits, or ZIP+4 with the hyphen: "90210-1234" — the ZipFormatUS enum picks the layout accepted in
Rejected: missing, oversized, malformed, or not a plausible ZIP	Empty string	Throws CkUSException — carries Input, Expected and Reason

Structural, not a lookup: it cannot tell whether the ZIP is assigned or deliverable.

Accepts exactly three layouts — 90210, 90210-1234, 902101234 — and rejects loose forms like "90210 1234". The nine-digit form is always returned with the hyphen. padLeadingZeros (on by default) repairs the commonest ZIP defect: a spreadsheet or an integer column that ate the leading zero. ZipFormatUS picks the layout you accept in.

CkUS.Zip("902101234");             // -> "90210-1234"
CkUS.Zip("2134");                  // -> "02134"  (leading zero restored)
CkUS.Zip(
    input: "2134",
    padLeadingZeros: false
);                                 // -> ""  (four digits is not a ZIP)

State

The state code or name.

string State(
    string? input = null,
    StateFormatUS output = StateFormatUS.Code,
    string? fallback = null,
    bool throwIfInvalid = CkSettings.DefaultThrowIfInvalid
)

Parameter	Type	Default	What it does
input	string?	null	The raw state value.
output	StateFormatUS	StateFormatUS.Code	The shape to return: the two-letter USPS code by default, the full name with StateFormatUS.Name.
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 "".
throwIfInvalid	bool	CkSettings.DefaultThrowIfInvalid (false)	Pass true to throw a CkUSException 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 state	The two-letter code: "NY" — the StateFormatUS enum picks code or name	The two-letter code: "NY" — the StateFormatUS enum picks code or name
Rejected: missing, oversized, or not a recognised state	Empty string	Throws CkUSException — carries Input, Expected and Reason

Matching ignores case, accents, punctuation and spacing — "D.C." and "US-CA" both resolve — but abbreviations like "Calif." do not.

Takes the two-letter USPS code or the full name, in any casing, and answers the code — or the name, when you ask with output: StateFormatUS.Name. It covers the 50 states, DC, the five inhabited territories and the three military designations.

CkUS.State(" NEW YORK ");          // -> "NY"
CkUS.State(
    input: "tx",
    output: StateFormatUS.Name
);                                 // -> "Texas"
CkUS.State("Calif.");              // -> ""  (only USPS codes and full names)

RoutingNumber

The bank's nine-digit code.

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

Parameter	Type	Default	What it does
input	string?	null	The raw routing number.
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 "".
throwIfInvalid	bool	CkSettings.DefaultThrowIfInvalid (false)	Pass true to throw a CkUSException 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 valid routing number	The nine digits: "021000021"	The nine digits: "021000021"
Rejected: missing, oversized, malformed, an unassigned prefix, or a failed checksum	Empty string	Throws CkUSException — carries Input, Expected and Reason

The checksum catches every single-digit typo — but a value can pass and still belong to no bank.

Validates the nine-digit ABA code that identifies a US bank (ABA = American Bankers Association). The value must start with an assigned prefix and pass the ABA checksum — a weighted sum of the digits that catches every single-digit typo.

CkUS.RoutingNumber("0210-0002-1"); // -> "021000021"  (separators dropped, checksum passes)
CkUS.RoutingNumber("021000022");   // -> ""  (one wrong digit — the checksum catches it)

AccountNumber

The bank account number.

string AccountNumber(
    string? input = null,
    int minLength = CkSettings.AccountMinLength,
    int maxLength = CkSettings.AccountMaxLength,
    string? fallback = null,
    bool throwIfInvalid = CkSettings.DefaultThrowIfInvalid
)

Parameter	Type	Default	What it does
input	string?	null	The raw account number.
minLength	int	CkSettings.AccountMinLength (4)	Fewest digits accepted. Values below 1 fall back to the default.
maxLength	int	CkSettings.AccountMaxLength (17)	Most digits accepted. Values below 1 fall back to the default; a range that cannot be satisfied rejects everything.
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 "".
throwIfInvalid	bool	CkSettings.DefaultThrowIfInvalid (false)	Pass true to throw a CkUSException 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 valid account number	The digits: "123456789"	The digits: "123456789"
Rejected: missing, oversized, holds anything but digits and separators, or a digit count outside the range	Empty string	Throws CkUSException — carries Input, Expected and Reason

This proves shape, nothing more — US account numbers carry no check digit.

Cleans a bank account number down to its digits: by default 4 to 17 of them (minLength / maxLength, from CkSettings.AccountMinLength and CkSettings.AccountMaxLength). There is no checksum to check — US account numbers have none — so this proves shape, nothing more.

CkUS.AccountNumber("12-3456 789"); // -> "123456789"
CkUS.AccountNumber("123");         // -> ""  (fewer than the 4-digit minimum)

Npi

The healthcare provider number.

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

Parameter	Type	Default	What it does
input	string?	null	The raw value.
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 "".
throwIfInvalid	bool	CkSettings.DefaultThrowIfInvalid (false)	Pass true to throw a CkUSException 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 valid NPI	The ten digits: "1234567893"	The ten digits: "1234567893"
Rejected: missing, oversized, malformed, wrong first digit, or a failed check digit	Empty string	Throws CkUSException — carries Input, Expected and Reason

Structural only — a value can pass and still not be registered.

Validates the ten-digit National Provider Identifier of a US healthcare provider. It must start with 1 (a person) or 2 (an organization) and carry the right Luhn check digit (the same checksum credit cards use).

CkUS.Npi("1234567893");            // -> "1234567893"  (the CMS example number)

Mbi

The Medicare card number.

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

Parameter	Type	Default	What it does
input	string?	null	The raw value.
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 "".
throwIfInvalid	bool	CkSettings.DefaultThrowIfInvalid (false)	Pass true to throw a CkUSException 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 valid MBI	The bare eleven characters, upper-cased: "1EG4TE5MK73"	The bare eleven characters, upper-cased: "1EG4TE5MK73"
Rejected: missing, oversized, the wrong length, or a position holding the wrong kind of character	Empty string	Throws CkUSException — carries Input, Expected and Reason

It proves the value could be an MBI, not that the beneficiary exists.

Validates the eleven-character Medicare Beneficiary Identifier from a Medicare card. Every position must be the right kind of character, and the letters S, L, O, I, B and Z never appear (they read too easily as digits).

CkUS.Mbi("1eg4-te5-mk73");         // -> "1EG4TE5MK73"

Dea

The prescriber number.

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

Parameter	Type	Default	What it does
input	string?	null	The raw value.
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 "".
throwIfInvalid	bool	CkSettings.DefaultThrowIfInvalid (false)	Pass true to throw a CkUSException 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 valid DEA number	The nine characters, upper-cased: "AB1234563"	The nine characters, upper-cased: "AB1234563"
Rejected: missing, oversized, malformed, or a failed check digit	Empty string	Throws CkUSException — carries Input, Expected and Reason

The check digit catches nearly every typo, but a value can pass and still belong to no registrant.

Validates a prescriber's DEA registration number: two letters (the second may be a 9, for a business address) and seven digits, the last a check digit.

CkUS.Dea("ab1234563");             // -> "AB1234563"

Cpt

The medical procedure code.

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

Parameter	Type	Default	What it does
input	string?	null	The raw value.
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 "".
throwIfInvalid	bool	CkSettings.DefaultThrowIfInvalid (false)	Pass true to throw a CkUSException 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 valid CPT code	The five characters: "1234F"	The five characters: "1234F"
Rejected: missing, oversized, malformed, or all zeros	Empty string	Throws CkUSException — carries Input, Expected and Reason

A CPT code carries no check digit, so this proves the shape, not that the code is assigned.

Validates the five-character procedure code on medical claims: five digits, or four digits and a trailing F, T or U.

CkUS.Cpt("1234f");                 // -> "1234F"

Icd10

The diagnosis code.

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

Parameter	Type	Default	What it does
input	string?	null	The raw value.
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 "".
throwIfInvalid	bool	CkSettings.DefaultThrowIfInvalid (false)	Pass true to throw a CkUSException 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 valid ICD-10 code	The dotted upper-case code: "A00.0"	The dotted upper-case code: "A00.0"
Rejected: missing, oversized, or malformed	Empty string	Throws CkUSException — carries Input, Expected and Reason

The shape is checked, not the code list — a well-formed code that was never assigned still passes.

Validates a diagnosis code. Bare or dotted in; the dotted form comes back, the one people read.

CkUS.Icd10("a000");                // -> "A00.0"
CkUS.Icd10("S72001A");             // -> "S72.001A"

AccountNumberMask, DeaMask, EinMask, MbiMask, PhoneMask and SsnMask are the display versions. Each validates with its matching method, then hides every character but the last few behind *. Two knobs: keepLast (how many trailing characters stay visible; default 4, capped at CkSettings.MaxMaskKeepLast) and maskChar (the hiding character; default '*').

Unlike everything else on this page, a mask never returns empty: a missing or invalid value comes back as the fully masked shape, so a label on screen never shows a raw or blank value.

SsnMask

The SSN, safe for screens.

string SsnMask(
    string? input = null,
    int keepLast = CkSettings.DefaultMaskKeepLast,
    char maskChar = '*',
    SsnFormatUS output = SsnFormatUS.Dashed
)

Parameter	Type	Default	What it does
input	string?	null	The raw value to mask.
keepLast	int	CkSettings.DefaultMaskKeepLast (4)	How many trailing characters stay visible. Capped at CkSettings.MaxMaskKeepLast (4); negatives count as 0.
maskChar	char	'*'	The replacement character. Whitespace and control characters fall back to '*'.
output	SsnFormatUS	SsnFormatUS.Dashed	The shape to mask in. Any keeps a valid value's own layout and uses the dashed shape for the placeholder.

Returns

When	You get
The value is valid	The masked value: "***-**-6789"
Missing or invalid	The fully masked placeholder: "***-**-****" — never empty, and it never throws

The display never leaks and never goes blank.

Masks a Social Security number. It also accepts ITINs, since they live in SSN fields, and output: SsnFormatUS picks the masked layout — dashed by default.

CkUS.SsnMask("123-45-6789");           // -> "***-**-6789"

PhoneMask

The phone number, safe for screens.

string PhoneMask(
    string? input = null,
    int keepLast = CkSettings.DefaultMaskKeepLast,
    char maskChar = '*',
    PhoneFormatUS output = PhoneFormatUS.National
)

Parameter	Type	Default	What it does
input	string?	null	The raw phone value to mask.
keepLast	int	CkSettings.DefaultMaskKeepLast (4)	How many trailing characters stay visible. Capped at CkSettings.MaxMaskKeepLast (4); negatives count as 0.
maskChar	char	'*'	The replacement character. Whitespace and control characters fall back to '*'.
output	PhoneFormatUS	PhoneFormatUS.National	The shape to mask in — the display form by default. Any keeps a valid value's own layout and uses the national shape for the placeholder.

Returns

When	You get
The value is valid	The masked value: "(***) ***-5678"
Missing or invalid	The fully masked placeholder: "(***) ***-****" — never empty, and it never throws

The display never leaks and never goes blank.

Masks a phone number; the masked layout follows output, PhoneFormatUS.National by default.

CkUS.PhoneMask("555.234.5678");        // -> "(***) ***-5678"

EinMask

The employer number, safe for screens.

string EinMask(
    string? input = null,
    int keepLast = CkSettings.DefaultMaskKeepLast,
    char maskChar = '*',
    EinFormatUS output = EinFormatUS.Dashed
)

Parameter	Type	Default	What it does
input	string?	null	The raw value to mask.
keepLast	int	CkSettings.DefaultMaskKeepLast (4)	How many trailing characters stay visible. Capped at CkSettings.MaxMaskKeepLast (4); negatives count as 0.
maskChar	char	'*'	The replacement character. Whitespace and control characters fall back to '*'.
output	EinFormatUS	EinFormatUS.Dashed	The shape to mask in. Any keeps a valid value's own layout and uses the dashed shape for the placeholder.

Returns

When	You get
The value is valid	The masked value: "**-***6789"
Missing or invalid	The fully masked placeholder: "**-*******" — never empty, and it never throws

The display never leaks and never goes blank.

Works like SsnMask for employer numbers; output: EinFormatUS picks the masked layout, dashed by default.

CkUS.EinMask("123456789");             // -> "**-***6789"

AccountNumberMask

The account number, safe for screens.

string AccountNumberMask(
    string? input = null,
    int keepLast = CkSettings.DefaultMaskKeepLast,
    char maskChar = '*',
    int minLength = CkSettings.AccountMinLength,
    int maxLength = CkSettings.AccountMaxLength
)

Parameter	Type	Default	What it does
input	string?	null	The raw account number to mask.
keepLast	int	CkSettings.DefaultMaskKeepLast (4)	How many trailing characters stay visible. Capped at CkSettings.MaxMaskKeepLast (4); negatives count as 0.
maskChar	char	'*'	The replacement character. Whitespace and control characters fall back to '*'.
minLength	int	CkSettings.AccountMinLength (4)	Fewest digits accepted; same rule as AccountNumber.
maxLength	int	CkSettings.AccountMaxLength (17)	Most digits accepted; same rule as AccountNumber.

Returns

When	You get
The value is valid	The masked value: "*****6789"
Missing or invalid	The fully masked placeholder: "********" — never empty, and it never throws

The display never leaks and never goes blank.

Masks a bank account number. It takes the same minLength / maxLength range as AccountNumber; there is no layout to pick — digits in, stars out.

CkUS.AccountNumberMask("12-3456 789"); // -> "*****6789"

MbiMask

The Medicare number, safe for screens.

string MbiMask(
    string? input = null,
    int keepLast = CkSettings.DefaultMaskKeepLast,
    char maskChar = '*'
)

Parameter	Type	Default	What it does
input	string?	null	The raw value to mask.
keepLast	int	CkSettings.DefaultMaskKeepLast (4)	How many trailing characters stay visible. Capped at CkSettings.MaxMaskKeepLast (4); negatives count as 0.
maskChar	char	'*'	The replacement character. Whitespace and control characters fall back to '*'.

Returns

When	You get
The value is valid	The masked value: "*******MK73"
Missing or invalid	The fully masked placeholder: "***********" — never empty, and it never throws

The display never leaks and never goes blank.

Masks the eleven-character Medicare Beneficiary Identifier; no layout options.

CkUS.MbiMask("1eg4-te5-mk73");         // -> "*******MK73"

DeaMask

The DEA number, safe for screens.

string DeaMask(
    string? input = null,
    int keepLast = CkSettings.DefaultMaskKeepLast,
    char maskChar = '*'
)

Parameter	Type	Default	What it does
input	string?	null	The raw value to mask.
keepLast	int	CkSettings.DefaultMaskKeepLast (4)	How many trailing characters stay visible. Capped at CkSettings.MaxMaskKeepLast (4); negatives count as 0.
maskChar	char	'*'	The replacement character. Whitespace and control characters fall back to '*'.

Returns

When	You get
The value is valid	The masked value: "*****4563"
Missing or invalid	The fully masked placeholder: "*********" — never empty, and it never throws

The display never leaks and never goes blank.

Masks a prescriber's DEA registration number; no layout options.

CkUS.DeaMask("junk");                  // -> "*********"  (invalid — fully masked, never blank)

The Is… twins

Every reader, as a yes or no.

Each reader above has a bool twin that answers the same question — "is this value valid under the reader's rules?" — without handing the cleaned value back. They take the reader's input knobs (the accepted layout, the account-number lengths) and drop the output and fallback ones. false does double duty, for "no" and for "not usable"; pass throwIfInvalid: true and the exception says what the reader would have said. When the value is going to be stored, call the reader and check for "" instead — same verdict, and you keep the value.

Twin	Of	Extra parameters
IsPhone(input, format, throwIfInvalid)	Phone	format — the layout the input must match, PhoneFormatUS, Loose by default
IsSsn(input, format, throwIfInvalid)	Ssn	format — SsnFormatUS, Any by default
IsItin(input, format, throwIfInvalid)	Itin	format — SsnFormatUS, Any by default
IsEin(input, format, throwIfInvalid)	Ein	format — EinFormatUS, Any by default
IsZip(input, format, padLeadingZeros, throwIfInvalid)	Zip	format — ZipFormatUS, Any by default; padLeadingZeros, true by default
IsState(input, throwIfInvalid)	State	—
IsRoutingNumber(input, throwIfInvalid)	RoutingNumber	—
IsAccountNumber(input, minLength, maxLength, throwIfInvalid)	AccountNumber	minLength and maxLength, the same defaults as the reader
IsNpi(input, throwIfInvalid)	Npi	—
IsMbi(input, throwIfInvalid)	Mbi	—
IsDea(input, throwIfInvalid)	Dea	—
IsCpt(input, throwIfInvalid)	Cpt	—
IsIcd10(input, throwIfInvalid)	Icd10	—

There is no IsTin: Tin already answers with the kind, and TinKindUS.Invalid is its "no".

CkUS.IsSsn("123 45 6789");                              // -> true
CkUS.IsSsn("123456789", format: SsnFormatUS.Dashed);    // -> false  (not the layout asked for)
CkUS.IsZip("2134");                                     // -> true   (a lost leading zero, restored)
CkUS.IsNpi("1234567890");                               // -> false  (the check digit fails)

InStates

Is it one of these states?

bool InStates(
    string? input = null,
    params IEnumerable<string?> states
)

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

Returns

When	You get
The value is a recognised state 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 licensing, tax-nexus and "we ship to these states" check. The value and every entry are read the way State reads them, so codes, names and the aliases mix freely on both sides. A params list must be last, so there is no throwIfInvalid; call State with it first when you need the exception.

CkUS.InStates("california", "CA", "Oregon", "wa");   // -> true
CkUS.InStates("Nevada", "CA", "Oregon", "wa");       // -> false
CkUS.InStates("junk", "CA");                         // -> false  (unrecognised matches nothing)

SamePhone

The same line, whatever the layout?

bool SamePhone(
    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 CkUSException that says which value is not a valid number and why, instead of answering false.

Returns

When	Default	With throwIfInvalid: true
Both are valid NANP numbers and the same one	true	true
Both are valid, and differ	false	false
Rejected: either value is not a valid number	false	Throws CkUSException — carries Input, Expected and Reason

(415) 555-0142, +1 415-555-0142 and 415.555.0142 are one line. Extensions are dropped by the loose reading, as Phone drops them, so x12 and x34 on the same number count as the same line — keep extensions in their own field. Two values that are not numbers are never the same.

CkUS.SamePhone("(415) 555-0142", "+14155550142");   // -> true
CkUS.SamePhone("415-555-0142", "415-555-0143");     // -> false
CkUS.SamePhone("junk", "junk");                     // -> false  (two unknowns)

SameTin

The same taxpayer id?

bool SameTin(
    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 CkUSException that says which value is not a valid identifier and why, instead of answering false.

Returns

When	Default	With throwIfInvalid: true
Both are valid identifiers of one kind, SSN, ITIN or EIN, with the same nine digits	true	true
Both are valid, and the kind or the digits differ	false	false
Rejected: either value is not a valid identifier	false	Throws CkUSException — carries Input, Expected and Reason

123-45-6789 and 123456789 are the same SSN. An SSN and an EIN that happen to share nine digits are different identifiers, and bare nine digits read as an SSN when they can, so 123456789 and the dashed EIN 12-3456789 are different kinds here — when the kind matters, capture the layout at the source, as Tin advises. For matching people and businesses across systems that format identifiers differently.

CkUS.SameTin("123-45-6789", "123456789");   // -> true
CkUS.SameTin("123456789", "12-3456789");    // -> false  (an SSN and an EIN)

HasPlus4

Does the ZIP carry its extension?

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

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

Returns

When	Default	With throwIfInvalid: true
A valid ZIP+4, hyphenated or as nine bare digits	true	true
A valid five-digit ZIP	false	false
Rejected: not a ZIP code	false	Throws CkUSException — carries Input, Expected and Reason

For mailing-quality checks. A five-digit ZIP is a valid ZIP that answers false; a value that is not a ZIP at all answers false too, or throws when asked.

CkUS.HasPlus4("90210-1234");   // -> true
CkUS.HasPlus4("902101234");    // -> true
CkUS.HasPlus4("90210");        // -> false

IsTollFree

An 8YY number?

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

Parameter	Type	Default	What it does
input	string?	null	The raw telephone number, in any loose layout.
throwIfInvalid	bool	CkSettings.DefaultThrowIfInvalid (false)	Pass true to throw a CkUSException that says why, instead of answering false, when the value is not a valid number.

Returns

When	Default	With throwIfInvalid: true
A valid number whose area code is 800, 833, 844, 855, 866, 877 or 888	true	true
Any other valid number	false	false
Rejected: not a valid number	false	Throws CkUSException — carries Input, Expected and Reason

For "not accepted as a personal contact number" and "cannot receive SMS" rules. The list is the one NANPA has assigned today; 822 is reserved for future toll-free use and does not count until it is.

CkUS.IsTollFree("800-555-0199");    // -> true
CkUS.IsTollFree("(555) 234-5678");  // -> false

IsTerritory

One of the five territories?

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

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

Returns

When	Default	With throwIfInvalid: true
American Samoa, Guam, the Northern Mariana Islands, Puerto Rico or the U.S. Virgin Islands	true	true
A state, the District of Columbia or a military designation	false	false
Rejected: not a recognised state	false	Throws CkUSException — carries Input, Expected and Reason

Shipping, tax and benefit rules often treat the territories apart from the fifty states. The District of Columbia is neither a state nor a territory and answers false here and in IsMilitary; check its code directly when it matters.

CkUS.IsTerritory("puerto rico");   // -> true
CkUS.IsTerritory("DC");            // -> false

IsMilitary

An armed-forces designation?

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

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

Returns

When	Default	With throwIfInvalid: true
AA (Armed Forces Americas), AE (Europe) or AP (Pacific)	true	true
A state, the District of Columbia or a territory	false	false
Rejected: not a recognised state	false	Throws CkUSException — carries Input, Expected and Reason

The three designations address mail to service members through military post offices rather than to a place, and carriers, tax rules and eligibility checks treat them apart.

CkUS.IsMilitary("AE");   // -> true
CkUS.IsMilitary("CA");   // -> false

InIcd10Ranges

Is the diagnosis in one of these groups?

bool InIcd10Ranges(
    string? input = null,
    params IEnumerable<string?> ranges
)

Parameter	Type	Default	What it does
input	string?	null	The raw ICD-10 code.
ranges	params IEnumerable<string?>	—	The groups to accept: prefixes such as "E11", and inclusive ranges such as "F20-F29". Null, empty, unreadable and contradictory entries are skipped.

Returns

When	You get
The value is a valid ICD-10 code inside a listed group	true
It is not a valid code, no group holds it, or the list is empty	false — an answer, not a failure; it never throws

The claims-logic check: "is this a mental-health diagnosis", "is this diabetes". The code and every bound are read the way Icd10 reads them. An entry without a dash is a prefix — "E11" covers the category and everything under it, "E11.6" covers "E11.65". Two codes joined by a dash are an inclusive range compared at the precision of the bounds: "F20-F29" holds every code whose category is F20 to F29, "E11.0-E11.9" every code under those subcategories, and the category "E11" itself is not under its own subcategories. Codes compare as their bare characters, without the dot. A params list must be last, so there is no throwIfInvalid; call Icd10 with it first.

CkUS.InIcd10Ranges("F25.0", "F20-F29");       // -> true
CkUS.InIcd10Ranges("E11.65", "E11");          // -> true   (the category and all beneath it)
CkUS.InIcd10Ranges("F41.1", "F01-F99");       // -> true   (mental and behavioural disorders)
CkUS.InIcd10Ranges("C00", "A00-B99");         // -> false

InCptRanges

Is the procedure in one of these groups?

bool InCptRanges(
    string? input = null,
    params IEnumerable<string?> ranges
)

Parameter	Type	Default	What it does
input	string?	null	The raw CPT code.
ranges	params IEnumerable<string?>	—	The groups to accept: single codes, matched exactly, and inclusive ranges such as "99201-99215". Null, empty, unreadable and contradictory entries are skipped.

Returns

When	You get
The value is a valid CPT code inside a listed group	true
It is not a valid code, no group holds it, or the list is empty	false — an answer, not a failure; it never throws

The claims-logic check: "is this an evaluation-and-management visit", "is this in the surgery section". The code and every bound are read the way Cpt reads them, and ranges compare character by character — the five characters are always the same length, so "0001F-0015F" works as well as "99201-99215". In a range list a dash means a range, so write single codes without one. A params list must be last, so there is no throwIfInvalid; call Cpt with it first.

CkUS.InCptRanges("99213", "99201-99215");             // -> true
CkUS.InCptRanges("99213", "99201-99215", "99381-99429");   // -> true  (any entry)
CkUS.InCptRanges("0055T", "0001F-0015F");             // -> false

IsPoBox

A box a parcel cannot go to.

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

Parameter	Type	Default	What it does
input	string?	null	The raw address line.
throwIfInvalid	bool	CkSettings.DefaultThrowIfInvalid (false)	Pass true to throw a CkUSException that says why, instead of answering false, when the value is empty.

Returns

When	Default	With throwIfInvalid: true
"P.O. Box 123", "PO Box 123", "Post Office Box 123", "POB 123", with or without #	true	true
A street address, or a private mailbox ("PMB 123"), which sits at a street address	false	false
Rejected: empty	false	Throws CkUSException — carries Input, Expected and Reason

The check a checkout must run before shipping. The line is cleaned as CkText.String cleans it.

CkUS.IsPoBox("PO Box 123, Springfield, IL");   // -> true
CkUS.IsPoBox("123 Main St");                    // -> false

Explain

Why not — in words, without an exception.

string Explain(
    string? input = null,
    string? what = nameof(Phone)
)

Parameter	Type	Default	What it does
input	string?	null	The raw value.
what	string?	nameof(Phone)	The reader to judge by, any of the fourteen: Ssn, Zip, Npi… case-insensitive.

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. what names the reader to judge by, each with its default layout rules.

CkUS.Explain("911-234-5678");                     // -> "the area code cannot be an N11 service code"
CkUS.Explain("000-00-0000", nameof(CkUS.Ssn));    // -> the reader's reason

Good to know

• All zeros is not a routing number. 000000000 adds up under the checksum and is still rejected, as the placeholder it is.
• Non-empty in, empty out means rejected. That is the standard CommonKit signal — check for "" where it matters. The masks are the one exception: they never return empty, so a masked display can't tell a hidden valid value from an invalid one. Call the validator itself when you need to know which it was.
• Shape is proven, truth is not. A value can pass every rule here and still belong to nobody — no method checks a registry. The checksums (RoutingNumber, Npi, Dea) catch typos; SSNs, EINs, ZIPs and account numbers have no check digit at all, so one typo there passes as easily as the real number.
• Phone is NANP-only and drops what doesn't belong. N11 area codes (211 … 911) and exchanges ending in 11 are rejected — those are service codes, not lines. An extension like x12 is dropped, not returned: keep extensions in their own field. A UK or German number answers ""; use CkIntl for the world.
• Bare nine digits are ambiguous. "123456789" could be an SSN or an EIN; Tin reports a valid-SSN-shaped value as an SSN. Only the dashed 12-3456789 layout is unambiguously an EIN — when the kind matters, capture the layout at the source.
• Letters are rejected, not skipped. "NPI 1234567893" fails — so a memo, a label or an IBAN never slips through as a bare number.
• Treat the results as sensitive. Never log or display an SSN, MBI or account number raw — that is what the mask twins are for.
• A fallback is checked too. It goes through the same cleaning and validation as the input; a fallback that is itself rejected answers "".
• The validators answer false, never "". The Is… twins, HasPlus4, IsTollFree, IsTerritory, IsMilitary, SamePhone and SameTin answer false both for "no" and for "not usable"; pass throwIfInvalid: true when the difference matters. InStates, InIcd10Ranges and InCptRanges never take the flag.
• SameTin compares kinds as well as digits. An SSN and an EIN with the same nine digits are different identifiers, and bare digits read as an SSN — the same ambiguity as above, resolved the same way: capture the layout at the source.
• The code-range checks know structure, not medicine. InIcd10Ranges and InCptRanges compare codes the way the code books order them; which ranges mean "mental health" or "surgery" is your list, from the specification you follow.

If you want errors instead

Pass throwIfInvalid: true and a value that cannot be used raises a CkUSException (from SafeCoder.CommonKit.Exceptions) instead of answering "" — or, for Tin, instead of answering TinKindUS.Invalid. The exception carries the Input, what was Expected and a short Reason, flattened into a one-line message. The …Mask methods take no throwIfInvalid at all — they are made for display and stay exception-free — and neither do InStates, InIcd10Ranges and InCptRanges, whose params list must be last; every other validator takes it and answers false otherwise.

CkUS.Ssn(
    input: "000-00-0000",
    throwIfInvalid: true
);   // throws CkUSException — the message says why