Name generator that produces culture-aware names and surnames. More...

#include <namegen.hpp>

Public Member Functions
	ng ()=default
	Default constructor — creates an empty generator with no names.

	ng (const ng &)=delete
	Not copyable.

ng &	operator= (const ng &)=delete
	Not copyable.

	ng (ng &&) noexcept=default
	Move constructor.

ng &	operator= (ng &&) noexcept=default
	Move assignment.

	~ng ()=default
	Default destructor.

name	get_name (const name_request &request)
	Generate a first name.

name	get_name (const name_request &request, std::uint64_t call_seed) const
	Generate a deterministic first name using a specific seed.

std::vector< name >	get_name_batch (const name_request &request, const core::batch_options &options)
	Generate a batch of name results from a seed drawn like get_name() draws its own.

std::vector< name >	get_name_batch (const name_request &request, const core::batch_options &options, std::uint64_t batch_seed) const
	Generate a batch of name results, deterministically.

template<typename Sink >
void	for_each_name (const name_request &request, const core::batch_options &options, std::uint64_t batch_seed, Sink &&sink) const
	Stream a batch of name results to a sink without holding the whole batch.

template<typename Sink >
void	for_each_name (const name_request &request, const core::batch_options &options, Sink &&sink)
	Stream a batch of name results with a batch seed drawn like get_name() draws its own.

name	get_surname (const name_request &request)
	Generate a surname.

name	get_surname (const name_request &request, std::uint64_t call_seed) const
	Generate a deterministic surname using a specific seed.

std::vector< name >	get_surname_batch (const name_request &request, const core::batch_options &options)
	Generate a batch of surname results from a seed drawn like get_surname() draws its own.

std::vector< name >	get_surname_batch (const name_request &request, const core::batch_options &options, std::uint64_t batch_seed) const
	Generate a batch of surname results, deterministically.

template<typename Sink >
void	for_each_surname (const name_request &request, const core::batch_options &options, std::uint64_t batch_seed, Sink &&sink) const
	Stream a batch of surname results to a sink without holding the whole batch.

template<typename Sink >
void	for_each_surname (const name_request &request, const core::batch_options &options, Sink &&sink)
	Stream a batch of surname results with a batch seed drawn like get_surname() draws its own.

bool	has_resources () const
	Check whether any name databases have been loaded.

void	load (const std::filesystem::path &resource_path)
	Load name files from a directory, replacing all names and layers loaded before.

bool	load (dataset tier)
	Load a dataset tier, replacing all names and layers loaded before.

void	extend (const std::filesystem::path &path, core::layer_mode mode=core::layer_mode::override)
	Add name layers from a `.names` file or a directory of them.

const core::layer_info &	extend_from_string (std::string_view text, std::string source, core::layer_mode mode=core::layer_mode::override)
	Add a name layer from text in the `.names` format.

const std::vector< core::layer_info > &	layers (culture c, gender g) const
	The layers in effect for one name list.

const std::vector< core::layer_info > &	surname_layers (culture c, gender g) const
	The layers in effect for the surnames of one gender.

std::uint64_t	data_hash () const
	Hash of the loaded names, recorded in each result's signature().

Static Public Member Functions
static ng &	instance ()
	Access the global singleton instance.

static culture	to_culture (std::wstring_view country_code)
	Translate an ISO 3166 2-letter country code to a culture enum.

static gender	to_gender (std::wstring_view gender_string)
	Translate a gender string to a gender enum.

static std::string_view	culture_code (culture c)
	The ISO 3166 2-letter country code of a culture.

static std::string_view	culture_name (culture c)
	The name of a culture.

Friends
class	name

struct	::ng_test_access

Detailed Description

Name generator that produces culture-aware names and surnames.

Generates realistic names by picking from popular name databases indexed by culture and gender, weighted by popularity. Supports 105 cultures.

Output is identical on every compiler and platform (dasmig-core): a seed, the same request and the same data give the same name everywhere.

Can be used as a singleton via instance() or constructed independently. Independent instances own their own name databases and random engine.

Thread safety: Each instance is independent. Concurrent calls to get_name() on the same instance require external synchronization. load() and extend() mutate internal state and must not be called concurrently with get_name() on the same instance.

Definition at line 320 of file namegen.hpp.

Constructor & Destructor Documentation

◆ ng()

dasmig::ng::ng ( )

default

Default constructor — creates an empty generator with no names.

Call load() to populate name databases before generating.

Member Function Documentation

◆ culture_code()

static std::string_view dasmig::ng::culture_code ( culture c )

inlinestatic

The ISO 3166 2-letter country code of a culture.

Parameters

c Culture.

Returns: Lower-case code such as "br", or "" for culture::any.

Definition at line 372 of file namegen.hpp.

◆ culture_name()

static std::string_view dasmig::ng::culture_name ( culture c )

inlinestatic

The name of a culture.

Parameters

c Culture.

Returns: Lower-case name such as "brazilian", or "any".

Definition at line 381 of file namegen.hpp.

◆ data_hash()

std::uint64_t dasmig::ng::data_hash ( ) const

inline

Hash of the loaded names, recorded in each result's signature().

Returns: The hash; 0 when nothing is loaded.

Definition at line 720 of file namegen.hpp.

◆ extend()

void dasmig::ng::extend	(	const std::filesystem::path &	path,
		core::layer_mode	mode = `core::layer_mode::override`
	)

inline

Add name layers from a .names file or a directory of them.

Each file names its culture and gender in its first two lines, so it adds to (or changes, or removes from) that list. A directory is applied all together, or not at all if any file is invalid.

Parameters

path	A `.names` file or a directory.
mode	How the layers combine with the names loaded before.

Exceptions

core::tsv_error	If a file cannot be read or is invalid; the names are then unchanged.
std::invalid_argument	If `path` is a file without the `.names` extension.

Definition at line 651 of file namegen.hpp.

◆ extend_from_string()

const core::layer_info & dasmig::ng::extend_from_string	(	std::string_view	text,
		std::string	source,
		core::layer_mode	mode = `core::layer_mode::override`
	)

inline

Add a name layer from text in the .names format.

Parameters

text	The country code, the list (`male`, `female` or `any` for surnames; `male-surname` or `female-surname` for the surnames of one gender), then one name per line with an optional weight.
source	Name used in errors.
mode	How the layer combines with the names loaded before.

Returns: What the layer did.

Exceptions

core::tsv_error If the text is invalid; the names are then unchanged.

Definition at line 680 of file namegen.hpp.

◆ for_each_name() [1/2]

template<typename Sink >

void dasmig::ng::for_each_name	(	const name_request &	request,
		const core::batch_options &	options,
		Sink &&	sink
	)

inline

Stream a batch of name results with a batch seed drawn like get_name() draws its own.

Template Parameters

Sink	Callable taking `(std::uint64_t, name&)`.

Parameters

request	What every item is generated from.
options	Count, first index, threads and uniqueness.
sink	Receives the items.

Definition at line 477 of file namegen.hpp.

◆ for_each_name() [2/2]

template<typename Sink >

void dasmig::ng::for_each_name	(	const name_request &	request,
		const core::batch_options &	options,
		std::uint64_t	batch_seed,
		Sink &&	sink
	)		const

inline

Stream a batch of name results to a sink without holding the whole batch.

Generates the same items as get_name_batch() and calls sink(index, item) in index order on the calling thread; index includes options.first.

Template Parameters

Sink	Callable taking `(std::uint64_t, name&)`; for example core::jsonl_writer or core::csv_writer.

Parameters

request	What every item is generated from.
options	Count, first index, threads and uniqueness.
batch_seed	Seed of the whole batch.
sink	Receives the items.

Definition at line 462 of file namegen.hpp.

◆ for_each_surname() [1/2]

template<typename Sink >

void dasmig::ng::for_each_surname	(	const name_request &	request,
		const core::batch_options &	options,
		Sink &&	sink
	)

inline

Stream a batch of surname results with a batch seed drawn like get_surname() draws its own.

Template Parameters

Sink	Callable taking `(std::uint64_t, name&)`.

Parameters

request	What every item is generated from.
options	Count, first index, threads and uniqueness.
sink	Receives the items.

Definition at line 574 of file namegen.hpp.

◆ for_each_surname() [2/2]

template<typename Sink >

void dasmig::ng::for_each_surname	(	const name_request &	request,
		const core::batch_options &	options,
		std::uint64_t	batch_seed,
		Sink &&	sink
	)		const

inline

Stream a batch of surname results to a sink without holding the whole batch.

Generates the same items as get_surname_batch() and calls sink(index, item) in index order on the calling thread; index includes options.first.

Template Parameters

Sink	Callable taking `(std::uint64_t, name&)`; for example core::jsonl_writer or core::csv_writer.

Parameters

request	What every item is generated from.
options	Count, first index, threads and uniqueness.
batch_seed	Seed of the whole batch.
sink	Receives the items.

Definition at line 559 of file namegen.hpp.

◆ get_name() [1/2]

name dasmig::ng::get_name ( const name_request & request )

inline

Generate a first name.

Parameters

request Gender and culture (both default to any).

Returns: A name object supporting chained appending.

Exceptions

std::invalid_argument If no names loaded for the resolved culture/gender.

Definition at line 391 of file namegen.hpp.

◆ get_name() [2/2]

name dasmig::ng::get_name	(	const name_request &	request,
		std::uint64_t	call_seed
	)		const

inline

Generate a deterministic first name using a specific seed.

Parameters

request	Gender and culture.
call_seed	Seed; the same seed, request and data give the same name on every platform.

Returns: A name object.

Exceptions

std::invalid_argument If no names loaded for the resolved culture/gender.

Definition at line 402 of file namegen.hpp.

◆ get_name_batch() [1/2]

std::vector< name > dasmig::ng::get_name_batch	(	const name_request &	request,
		const core::batch_options &	options
	)

inline

Generate a batch of name results from a seed drawn like get_name() draws its own.

Item i is get_name(request, core::item_seed(batch_seed, options.first + i)) for the drawn batch seed; see the seeded overload.

Parameters

request	What every item is generated from.
options	Count, first index, threads and uniqueness.

Returns: The results, in index order.

Definition at line 419 of file namegen.hpp.

◆ get_name_batch() [2/2]

std::vector< name > dasmig::ng::get_name_batch	(	const name_request &	request,
		const core::batch_options &	options,
		std::uint64_t	batch_seed
	)		const

inline

Generate a batch of name results, deterministically.

Item i is exactly get_name(request, core::item_seed(batch_seed, options.first + i)), so an item replays on its own, a range can be generated directly, two batches that follow each other equal one, and the output does not depend on options.threads.

Parameters

request	What every item is generated from.
options	Count, first index, threads and uniqueness (see core::unique_rule; the rule must be made for `name`).
batch_seed	Seed of the whole batch.

Returns: The results, in index order.

Exceptions

std::invalid_argument	If the request or options are invalid.
std::runtime_error	If no data has been loaded, or a unique batch runs out of attempts.

Definition at line 440 of file namegen.hpp.

◆ get_surname() [1/2]

name dasmig::ng::get_surname ( const name_request & request )

inline

Generate a surname.

Parameters

request Culture, and gender for cultures with gendered surnames (both default to any).

Returns: A name object supporting chained appending.

Exceptions

std::invalid_argument If no surnames loaded for the resolved culture.

Definition at line 489 of file namegen.hpp.

◆ get_surname() [2/2]

name dasmig::ng::get_surname	(	const name_request &	request,
		std::uint64_t	call_seed
	)		const

inline

Generate a deterministic surname using a specific seed.

Parameters

request	Culture and gender.
call_seed	Seed for reproducible results.

Returns: A name object.

Exceptions

std::invalid_argument If no surnames loaded for the resolved culture.

Definition at line 499 of file namegen.hpp.

◆ get_surname_batch() [1/2]

std::vector< name > dasmig::ng::get_surname_batch	(	const name_request &	request,
		const core::batch_options &	options
	)

inline

Generate a batch of surname results from a seed drawn like get_surname() draws its own.

Item i is get_surname(request, core::item_seed(batch_seed, options.first + i)) for the drawn batch seed; see the seeded overload.

Parameters

request	What every item is generated from.
options	Count, first index, threads and uniqueness.

Returns: The results, in index order.

Definition at line 516 of file namegen.hpp.

◆ get_surname_batch() [2/2]

std::vector< name > dasmig::ng::get_surname_batch	(	const name_request &	request,
		const core::batch_options &	options,
		std::uint64_t	batch_seed
	)		const

inline

Generate a batch of surname results, deterministically.

Item i is exactly get_surname(request, core::item_seed(batch_seed, options.first + i)), so an item replays on its own, a range can be generated directly, two batches that follow each other equal one, and the output does not depend on options.threads.

Parameters

request	What every item is generated from.
options	Count, first index, threads and uniqueness (see core::unique_rule; the rule must be made for `name`).
batch_seed	Seed of the whole batch.

Returns: The results, in index order.

Exceptions

std::invalid_argument	If the request or options are invalid.
std::runtime_error	If no data has been loaded, or a unique batch runs out of attempts.

Definition at line 537 of file namegen.hpp.

◆ has_resources()

bool dasmig::ng::has_resources ( ) const

inline

Check whether any name databases have been loaded.

Returns: true if at least one name list is loaded.

Definition at line 583 of file namegen.hpp.

◆ instance()

static ng & dasmig::ng::instance ( )

inlinestatic

Access the global singleton instance.

Loads the lite tier on first access (or full when lite is not found), from compiled-in data or an auto-probed resources/. For independent generators, prefer constructing a separate ng instance.

Returns: Reference to the global ng instance.

Definition at line 340 of file namegen.hpp.

◆ layers()

const std::vector< core::layer_info > & dasmig::ng::layers	(	culture	c,
		gender	g
	)		const

inline

The layers in effect for one name list.

Parameters

c	Culture.
g	gender::m or gender::f for forenames, gender::any for surnames.

Returns: The layer records.

Exceptions

std::out_of_range If that list was never loaded.

Definition at line 697 of file namegen.hpp.

◆ load() [1/2]

void dasmig::ng::load ( const std::filesystem::path & resource_path )

inline

Load name files from a directory, replacing all names and layers loaded before.

Reads every .names file below resource_path, in path order (see doc/usage.md for the format). A path that is not a directory is ignored.

Parameters

resource_path Directory containing .names files, such as resources/lite.

Exceptions

core::tsv_error If a file is malformed; the names are then unchanged.

Definition at line 599 of file namegen.hpp.

◆ load() [2/2]

bool dasmig::ng::load ( dataset tier )

inline

Load a dataset tier, replacing all names and layers loaded before.

lite uses the compiled-in copy when built with DASMIG_NAME_EMBED. Otherwise the tier is read from the first of resources, ../resources, name-generator/resources and ../name-generator/resources that has it.

Parameters

tier	The dataset size to load (dataset::lite or dataset::full).

Returns: true if the tier was found and loaded.

Exceptions

core::tsv_error If a file is malformed.

Definition at line 617 of file namegen.hpp.

◆ surname_layers()

const std::vector< core::layer_info > & dasmig::ng::surname_layers	(	culture	c,
		gender	g
	)		const

inline

The layers in effect for the surnames of one gender.

Parameters

c	Culture.
g	gender::m or gender::f; gender::any is the surname list shared by both.

Returns: The layer records.

Exceptions

std::out_of_range If that list was never loaded (a culture has one only when its surnames change with gender).

Definition at line 709 of file namegen.hpp.

◆ to_culture()

static culture dasmig::ng::to_culture ( std::wstring_view country_code )

inlinestatic

Translate an ISO 3166 2-letter country code to a culture enum.

Parameters

country_code Two-letter country code (e.g., L"us", L"br").

Returns: Matching culture, or culture::any if not recognized.

Definition at line 349 of file namegen.hpp.

◆ to_gender()

static gender dasmig::ng::to_gender ( std::wstring_view gender_string )

inlinestatic

Translate a gender string to a gender enum.

Parameters

gender_string Gender string (e.g., L"male", L"female", L"m", L"f").

Returns: Matching gender, or gender::any if not recognized.

Definition at line 362 of file namegen.hpp.

Friends And Related Symbol Documentation

◆ ::ng_test_access

friend struct ::ng_test_access

friend

Definition at line 1177 of file namegen.hpp.

◆ name

friend class name

friend

Definition at line 1176 of file namegen.hpp.

The documentation for this class was generated from the following file:

dasmig/namegen.hpp

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ ng()

Member Function Documentation

◆ culture_code()

◆ culture_name()

◆ data_hash()

◆ extend()

◆ extend_from_string()

◆ for_each_name() [1/2]

◆ for_each_name() [2/2]

◆ for_each_surname() [1/2]

◆ for_each_surname() [2/2]

◆ get_name() [1/2]

◆ get_name() [2/2]

◆ get_name_batch() [1/2]

◆ get_name_batch() [2/2]

◆ get_surname() [1/2]

◆ get_surname() [2/2]

◆ get_surname_batch() [1/2]

◆ get_surname_batch() [2/2]

◆ has_resources()

◆ instance()

◆ layers()

◆ load() [1/2]

◆ load() [2/2]

◆ surname_layers()

◆ to_culture()

◆ to_gender()

Friends And Related Symbol Documentation

◆ ::ng_test_access

◆ name