API Reference

API reference

Everything public is in the namespace RandomNameGeneratorLibrary, in one assembly with no dependencies. This page describes 2.3.0. No public type or member has been renamed or removed since 1.2.2; additions carry the version that introduced them. The same text is in the package's XML documentation, so IntelliSense shows it too.

The three generators

PersonNameGenerator, PlaceNameGenerator and StarNameGenerator (2.2.0) have the same three constructors.

Constructor	What it does
new PersonNameGenerator()	Fresh randomness. On .NET 6 and later the generator draws from Random.Shared. On .NET Framework and other netstandard2.0 hosts it gets its own Random with a seed from a process-wide source, so two generators made in the same instant give different names.
new PersonNameGenerator(Random randGen)	Draws from your Random. A seeded instance gives reproducible names. Throws ArgumentNullException for null.
new PersonNameGenerator(int seed) (2.1.0)	The same as passing new Random(seed).

Every generating method makes one Random.Next(0, listLength) call per name it picks; Reproducible names lists the exact calls.

PersonNameGenerator

Implements IPersonNameGenerator. Names come from the 1990 US Census lists: 1,219 male first names, 4,275 female first names and 88,799 last names, all Title case ASCII.

Member	Returns	Notes
GenerateRandomFirstAndLastName()	string	A first name of either gender, a space, a last name. Seed 42 gives Alisa Streets.
GenerateRandomFirstName()	string	Picks male or female with equal probability, then a name from that list. Any one male name is about 3.5 times likelier than any one female name because the male list is shorter.
GenerateRandomMaleFirstName()	string	Seed 42 gives Morton.
GenerateRandomFemaleFirstName()	string	Seed 42 gives Marguerita.
GenerateRandomLastName()	string	Seed 42 gives Vis.
GenerateRandomMaleFirstAndLastName()	string
GenerateRandomFemaleFirstAndLastName()	string
GenerateMultipleFirstAndLastNames(int count)	IEnumerable<string>	count names, built before the call returns. Zero gives an empty sequence; negative throws ArgumentOutOfRangeException.
GenerateMultipleMaleFirstAndLastNames(int count)	IEnumerable<string>
GenerateMultipleFemaleFirstAndLastNames(int count)	IEnumerable<string>
GenerateMultipleMaleFirstNames(int count)	IEnumerable<string>
GenerateMultipleFemaleFirstNames(int count)	IEnumerable<string>
GenerateMultipleLastNames(int count)	IEnumerable<string>
PersonNameGenerator.MaleFirstNames (static, 2.1.0)	IReadOnlyList<string>	1,219 names; James first.
PersonNameGenerator.FemaleFirstNames (static, 2.1.0)	IReadOnlyList<string>	4,275 names; Mary first.
PersonNameGenerator.LastNames (static, 2.1.0)	IReadOnlyList<string>	88,799 names; Smith first.

There is no multiple version of GenerateRandomFirstName (either gender, first name only). Loop, or use Enumerable.Range(0, n).Select(_ => people.GenerateRandomFirstName()).

PlaceNameGenerator

Implements IPlaceNameGenerator. Names come from the Census 2000 places file, one entry per distinct name.

Member	Returns	Notes
GenerateRandomPlaceName()	string	Seed 42 gives Boardman.
GenerateMultiplePlaceNames(int numberOfNames)	IEnumerable<string>	Zero gives an empty sequence; negative throws ArgumentOutOfRangeException.
PlaceNameGenerator.PlaceNames (static, 2.1.0)	IReadOnlyList<string>	16,969 names; Abbeville first, Yaurel comunidad last.

StarNameGenerator (2.2.0)

Implements IStarNameGenerator. Three kinds of name; Name lists and data sources says where each comes from.

Member	Returns	Notes
GenerateRandomStarName()	string	One of 3,716 named stars: the 640 IAU proper names and the 3,076 Bayer and Flamsteed designations, all equally likely. Seed 42 gives Delta² Gruis.
GenerateRandomProperStarName()	string	IAU proper names only. Seed 42 gives Parumleo.
GenerateRandomCatalogStarName()	string	HD 1 to HD 225300, or one of the 118,218 Hipparcos numbers as HIP n. Seed 42 gives HIP 4210.
GenerateMultipleStarNames(int numberOfNames)	IEnumerable<string>	Named stars, as GenerateRandomStarName. Zero gives an empty sequence; negative throws ArgumentOutOfRangeException.
StarNameGenerator.ProperStarNames (static)	IReadOnlyList<string>	640 names; Absolutno first.
StarNameGenerator.DesignatedStarNames (static)	IReadOnlyList<string>	3,076 names; 1 Aquarii first.
StarNameGenerator.StarNames (static)	IReadOnlyList<string>	3,716 names: the proper names followed by the designations.
StarNameGenerator.CatalogStarNameCount (static)	int	343,518.

There are no multiple versions of the proper and catalogue methods.

Interfaces

IPersonNameGenerator, IPlaceNameGenerator and IStarNameGenerator declare the generating methods of their class, without the constructors or the static lists. Register a generator against its interface in a dependency injection container, or mock the interface in tests. Star names arrived in 2.2.0 with their own interface rather than as new members on an existing one. Your own implementations of the older interfaces therefore kept compiling.

Extension methods on System.Random

Three static classes give System.Random the same methods. Each call wraps the Random in a new generator, so a seeded Random gives reproducible names and several calls on one Random continue one sequence.

Class	Methods
RandomPersonNameExtensions	The thirteen methods of IPersonNameGenerator, from GenerateRandomFirstName() to GenerateMultipleLastNames(int numberOfNames).
RandomPlaceNameExtensions	GenerateRandomPlaceName() and GenerateMultiplePlaceNames(int numberOfNames).
RandomStarNameExtensions	GenerateRandomStarName() and GenerateMultipleStarNames(int numberOfNames). There are no extensions for proper or catalogue star names; wrap the Random in a StarNameGenerator instead.

A null Random throws ArgumentNullException; a negative count throws ArgumentOutOfRangeException.

Parameter names

The count parameter is count on PersonNameGenerator and IPersonNameGenerator, and numberOfNames on the place and star generators and on every extension method. It matters only for named arguments: people.GenerateMultipleLastNames(count: 5) and places.GenerateMultiplePlaceNames(numberOfNames: 5). The Random parameter is randGen on the constructors and rand on the extension methods.

Exceptions

Exception	When
ArgumentNullException	A null Random passed to a constructor (parameter randGen) or used as the receiver of an extension method (parameter rand).
ArgumentOutOfRangeException	A negative count. The message reads The number of names to generate cannot be negative.
OutOfMemoryException	A count too large to allocate, such as int.MaxValue. The list is allocated up front, so this is thrown before any name is generated.
InvalidOperationException	An embedded list is missing from the assembly. This cannot happen with an intact package; the message names the resource.

Nothing else throws. There is no exception for a bad seed, because every int is a valid seed.

Obsolete and hidden types

• BaseNameGenerator is the public abstract base of the three generators. It is hidden from IntelliSense and is not meant to be used or derived from; it stays public for binary compatibility with 1.x. Its protected members are the Random field RandGen and ReadResourceByLine(string resourceFileName).
• CensusListStripper and FileCompressor are the 2014 one-off tools that produced the lists. They are marked [Obsolete] since 2.1.0, compile with warning CS0618, and will be removed in 3.0. The maintained replacement is the tools/CensusTools console project in the repository, which is not part of the package.

Thread safety

The lists are parsed once per process, on first use, and are safe to read from any thread. On .NET 6 and later a generator from the default constructor draws from Random.Shared and can be shared between threads. A generator built around a Random you supplied, and every extension method call, is only as thread-safe as that Random. Random is not thread-safe at all, so use one generator per thread, or a lock. On .NET Framework and other netstandard2.0 hosts the default constructor also produces a plain Random per generator, so one generator per thread is the safe pattern there too.