Person names

Rules only. PersonName, NameParsing.Classify/Split/SplitMany and NameHints read a string, give every part with offsets into the input (UTF-16 chars), and say in ParseDetail which issues were met. Nothing is inferred: no gender, origin or salutation, and no part is added that the text did not contain. CultureInfo never affects a result; comparison is ordinal and case folding is our own invariant folding.

Hints

NameHints(Region? country, string? language) is optional. A hint never overrules the text; it chooses between readings the text leaves open:

Classes

NameClass is Person, Company, Multiple or Unknown.

• Company: a legal form of the ELF list (docs/company-names.md), a company word (Ltd-like words, "Holdings", "Associates", ...), a trading-as or care-of marker, or a comma part that is itself a company ("Kvarner Promet d.d., Jansen"). A company word after a given name that is also a surname ("Jane Baker") does not make a company.
• Multiple: connectors between name parts (and, &, et, und, en, e, og, och, ja, i, ...), semicolons and line breaks, and comma lists ending in a connector. "Mr & Mrs John Smith": a title-only part takes the whole name that follows. "John and Jane Smith": a lone word before a full name is a given name and shares the family name. "Maria Garcia y Lopez": y/e/i between two family names is one person (the right side is one word, with particles). Two single words joined by a connector are Multiple only when the first is a known given name ("Johnson & Johnson" is Unknown). Every part must also read as a person when parsed again alone, otherwise the whole text is Unknown.
• Person: everything else with 2 to 8 words. When nothing proves a person (no title, suffix, nickname, particle, comma order, initial or known given name) the result carries the info issue person.no-evidence.
• Unknown: one bare word, titles and suffixes alone (person.no-name), digits or @, more than 8 words, more than 8 people, or text that reads as a company once put in reading order (person.not-a-person). PersonName.Parse still accepts one bare word (flag SingleWord).

Parts

Prefix (titles), Given, Middle, Nickname, Particle, Family, SecondFamily, Suffix (generational), ProfessionalSuffix, Order.

• Titles are read from the start of each comma segment: academic, military, religious, honorifics, up to three words, dotted runs such as Prof.Dr.. A stray dash or ampersand before the titles is skipped. Titles are scoped by language so that words that are names elsewhere are not stripped.
• Suffixes are peeled from the end: generational (Jr, Sr, II, III), professional (PhD, MD, Esq, ...; a bare one needs a dot or its own comma segment).
• Nicknames: quoted ("Bob", curly and guillemet quotes) or parenthesized. A quote mark opens one only at the start of a word and closes it only at the end of one (O'Brien, l'Heureux are not nicknames); a quoted run that holds a comma is a stray mark and is ignored.
• Order: "Family, Given Middle" (trailing particles after the given names move to the family name: "Berg, Jan van den"), given-first, family-first for hu.
• Particles (van, van der, de, de la, von, da, dos, di, le, ...) stay in Particle, apart from Family.
• Spanish-style second family names with a hint; a three-word name whose middle word is the second half of a compound given name ("Ana Maria Garcia") keeps one family name.

Canonical form

Always given-first reading order: "Smith, John" gives John Smith, and Hungarian "Kovács János" gives János Kovács; Order remembers the input order. This keeps the JSON round trip stable. Nicknames are written "Nick", professional suffixes after a comma (, PhD), generational suffixes inline. Mixed-case input is kept as written. A reparse of a family-first canonical form with the hu hint is not idempotent, by design.

Casing restoration

Applied only when the whole input is one case (at least two letters, all upper or all lower). Each restored part says so with the info issue person.casing-restored, and keeps the offsets of the original.

• Capital first letter of each word; hyphen and apostrophe parts too (O'BRIEN gives O'Brien, ANNE-MARIE gives Anne-Marie).
• Mc followed by a capital (MCDONALD gives McDonald). Mac is not restored: MACDONALD gives Macdonald, because Mac prefixes are too often not a prefix (MACHADO).
• Particles are lower case only with a non-English hint (not Irish): VAN DER BERG gives Van Der Berg without a hint and van der Berg with nl.

Person key V1

See docs/name-keys.md.

Black-box comparison

tools/Oracles/Names runs, from released packages and never reading them: python-nameparser 2.8.2 (used through HumanName, as its documentation describes), probablepeople 0.5.6, cleanco 2.3 (Python, in a uv venv) and NameParserSharp 1.5.0 (NuGet, in the oracle project only), over testdata/names/gold.tsv: 522 synthetic person and company strings with gold parts, 28 languages, made by make-gold.py with seed 20261105. score.py scores token accuracy (each gold part's words get the reference's label), class accuracy and legal-form detection. The gold set is made from the same kind of templates our rules were written against, so our scores are near 100% by construction. The comparison is information about the references' coverage of these languages, not a quality claim for real-world text.

Iberian, Irish, Maltese and Slavic forms

Rules only; they read the words of a name and say nothing about gender, origin or salutation.

• Titles Mons., Msgr., Monsignor, Mestre/Mestra, Revd, Rt Hon are prefixes (the ambiguous ones only with a language hint). Sen., Senator, Hon., Rev. and Fr. were already prefixes.
• Portuguese: a particle two words from the end keeps its family name: Ana Maria dos Santos Ferreira is given Ana, middle Maria, particle dos, family Santos, second family Ferreira. In a Family, Given text a connector between two family names (Garcia y Lopez, Maria) is one person.
• Irish Mac standing apart (Padraig Mac Giolla) is a particle with an Irish hint; Ó, Ní, Nic, Uí and Mhic already were. Maltese ta, tal, tas, tat and il written apart are particles with a Maltese hint (Josef ta' Cassar); written with a hyphen (Il-Borg) they stay in the family name.
• Czech, Slovak, Croatian and Slovenian: two words read as Surname Given when the second is a listed given name and the first is not, or the first is a feminine -ová surname form and the second is not (Novák Jan, Nováková Jana). Names that are also common surnames (Marek, Martin, Matej) are not listed, so Marek Jan and Jan Marek keep the order as written. The given-name list is our own.
• Degrees: MgA., BcA., Prom., PharmDr., ThLic., ThMgr. (cs, sk), dipl. iur., dipl. oec., mag. oec., dr. med., dent., bacc., spec., struč. (hr) are prefixes; CSc., DrSc. and DiS. after a comma or with dots are suffixes.
• A title after the name is a title: Novák Jan Ing., Jana Nováková Ing., Ivan Horvat dipl. ing. give the prefix Ing. (dipl. ing.) when the language hint lists the words as titles, they end in a period, have at least two letters and a name stands before them (a single letter with a period, P., is an initial). With a title in front already, the later one joins the professional suffixes. Registers and signatures of the Czech Republic, Slovakia and Croatia write degrees this way; the words are the lists already used for the leading position.
• More credentials after a comma or a name are professional suffixes: EMBA, BBA, MIM, ACCA, FCCA, FACCA, FRCP, MRCP, MBChB, MPhil, MEng, FCA, CMA, ACMA, FCMA, CGMA, FCPA, MHA, FRM, PRM are suffixes anywhere; CIA, CFE, MArch, MSt, MRes, MAS, ACA, CAIA need a dot or a comma (they are also words). The casing of each is fixed when casing is restored.
• The given-name lists used for the Czech, Slovak, Croatian and Slovenian Surname Given order, and for telling two people from a company, were widened with common names of those languages and the Nordic ones (our own lists; names that are also common surnames are still left out of the Slavic list).