Email Generator: email addresses in each country's style. More...

#include <emailgen.hpp>

Public Member Functions
	emg ()
	Default constructor — creates an empty generator with no data.

	emg (const emg &)=delete
	Not copyable.

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

	emg (emg &&) noexcept=default
	Movable.

emg &	operator= (emg &&) noexcept=default
	Movable.

	~emg ()=default
	Destructor.

email	get_email (const email_request &request)
	Generate a random email address. Use email_request{} for the defaults.

email	get_email (const email_request &request, std::uint64_t call_seed) const
	Generate a deterministic email address.

std::vector< email >	get_email_batch (const email_request &request, const core::batch_options &options)
	Generate a batch of email results from a seed drawn like get_email() draws its own.

std::vector< email >	get_email_batch (const email_request &request, const core::batch_options &options, std::uint64_t batch_seed) const
	Generate a batch of email results, deterministically.

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

template<typename Sink >
void	for_each_email (const email_request &request, const core::batch_options &options, Sink &&sink)
	Stream a batch of email results with a batch seed drawn like get_email() draws its own.

bool	has_data () const
	Check whether any data has been loaded.

std::size_t	country_count () const
	Return the number of countries loaded.

const std::vector< std::string > &	countries () const
	The countries an address can be generated for.

bool	has_country (std::string_view country) const
	Whether a country is loaded.

void	load (const std::filesystem::path &dir)
	Load data from a resource directory, replacing all data and layers loaded before.

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

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

const core::layer_info &	extend (email_table which, core::tsv_document doc, core::layer_mode mode=core::layer_mode::override)
	Add a data layer to one table.

const core::layer_info &	extend_from_string (email_table which, std::string_view text, std::string source, core::layer_mode mode=core::layer_mode::override)
	Add a data layer to one table from TSV text (for example from a WebAssembly host).

const std::vector< core::layer_info > &	layers (email_table which) const
	The layers in effect for one table, in order.

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

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

Detailed Description

Email Generator: email addresses in each country's style.

A call draws a country (by population), a style of the country's profile ("style"), the handle words ("local"), the digits ("number") and the domain ("domain"), each from a stream split from the call seed. Output is identical on every compiler and platform (dasmig-core).

Can be used as a singleton via instance() or constructed independently.

Thread safety: Each instance is independent. Concurrent calls to get_phone(request, seed) on the same instance are safe; calls that use the instance engine, loading and extending require external synchronisation.

Definition at line 174 of file emailgen.hpp.

Constructor & Destructor Documentation

◆ emg()

dasmig::emg::emg ( )

inline

Default constructor — creates an empty generator with no data.

Definition at line 179 of file emailgen.hpp.

Member Function Documentation

◆ countries()

const std::vector< std::string > & dasmig::emg::countries ( ) const

inline

The countries an address can be generated for.

Returns: Their ISO-3166 two-letter codes (upper case), in the order of countries.tsv; the list a request's country is chosen from.

Definition at line 312 of file emailgen.hpp.

◆ country_count()

std::size_t dasmig::emg::country_count ( ) const

inline

Return the number of countries loaded.

Returns: The count; it is countries().size().

Definition at line 307 of file emailgen.hpp.

◆ data_hash()

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

inline

Hash of the loaded data (all tables), recorded in each result's signature().

Returns: The hash; 0 when nothing is loaded.

Definition at line 445 of file emailgen.hpp.

◆ extend() [1/2]

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

inline

Add data layers from a directory or a file.

A directory may hold any of the table files (see email_table); all are applied together or, if any fails, none. A file must have one of those names.

Parameters

path	Directory or file.
mode	How the layers combine with the data loaded before.

Exceptions

core::tsv_error	If a file cannot be read or a row is invalid; the data is then unchanged.
std::invalid_argument	If `path` is a file with another name.

Definition at line 379 of file emailgen.hpp.

◆ extend() [2/2]

const core::layer_info & dasmig::emg::extend	(	email_table	which,
		core::tsv_document	doc,
		core::layer_mode	mode = `core::layer_mode::override`
	)

inline

Add a data layer to one table.

Rows are keyed by the table's key columns (see doc/data.md). In the default override mode a row replaces the loaded row with the same key and new keys are added; a row with disabled set to 1 removes its key.

Parameters

which	The table.
doc	TSV with that table's columns.
mode	How the layer combines with the data loaded before.

Returns: What the layer did (rows added, replaced, removed, warnings).

Exceptions

core::tsv_error If a row is invalid; the data is unchanged.

Definition at line 411 of file emailgen.hpp.

◆ extend_from_string()

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

inline

Add a data layer to one table from TSV text (for example from a WebAssembly host).

Parameters

which	The table.
text	TSV with that table's columns.
source	Name used in errors.
mode	How the layer combines with the data loaded before.

Returns: What the layer did.

Exceptions

core::tsv_error If a row is invalid; the data is unchanged.

Definition at line 428 of file emailgen.hpp.

◆ for_each_email() [1/2]

template<typename Sink >

void dasmig::emg::for_each_email	(	const email_request &	request,
		const core::batch_options &	options,
		Sink &&	sink
	)

inline

Stream a batch of email results with a batch seed drawn like get_email() draws its own.

Template Parameters

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

Parameters

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

Definition at line 294 of file emailgen.hpp.

◆ for_each_email() [2/2]

template<typename Sink >

void dasmig::emg::for_each_email	(	const email_request &	request,
		const core::batch_options &	options,
		std::uint64_t	batch_seed,
		Sink &&	sink
	)		const

inline

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

Template Parameters

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

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 279 of file emailgen.hpp.

◆ get_email() [1/2]

email dasmig::emg::get_email ( const email_request & request )

inline

Generate a random email address. Use email_request{} for the defaults.

Parameters

request What to generate.

Returns: The address.

Exceptions

std::runtime_error	If no email data has been loaded.
std::invalid_argument	If the country is unknown.

Definition at line 206 of file emailgen.hpp.

◆ get_email() [2/2]

email dasmig::emg::get_email	(	const email_request &	request,
		std::uint64_t	call_seed
	)		const

inline

Generate a deterministic email address.

Parameters

request	What to generate.
call_seed	Seed; the same request, seed and data give the same result. Does not touch the instance engine.

Returns: The address.

Exceptions

std::runtime_error	If no email data has been loaded.
std::invalid_argument	If the country is unknown.

Definition at line 215 of file emailgen.hpp.

◆ get_email_batch() [1/2]

std::vector< email > dasmig::emg::get_email_batch	(	const email_request &	request,
		const core::batch_options &	options
	)

inline

Generate a batch of email results from a seed drawn like get_email() draws its own.

Parameters

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

Returns: The results, in index order.

Definition at line 244 of file emailgen.hpp.

◆ get_email_batch() [2/2]

std::vector< email > dasmig::emg::get_email_batch	(	const email_request &	request,
		const core::batch_options &	options,
		std::uint64_t	batch_seed
	)		const

inline

Generate a batch of email results, deterministically.

Item i is exactly get_email(request, core::item_seed(batch_seed, options.first + i)); see get_phone_batch().

Parameters

request	What every item is generated from.
options	Count, first index, threads and uniqueness (the rule must be made for `email`).
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 263 of file emailgen.hpp.

◆ has_country()

bool dasmig::emg::has_country ( std::string_view country ) const

inline

Whether a country is loaded.

Parameters

country ISO-3166 two-letter code (any case).

Returns: True when countries.tsv has the country.

Definition at line 317 of file emailgen.hpp.

◆ has_data()

bool dasmig::emg::has_data ( ) const

inline

Check whether any data has been loaded.

Returns: True when at least one country is loaded.

Definition at line 303 of file emailgen.hpp.

◆ instance()

static emg & dasmig::emg::instance ( )

inlinestatic

Access the global singleton instance.

Loads the lite tier (or full if lite is missing) on first access, from compiled-in data or an auto-probed resources/.

Returns: The singleton.

Definition at line 192 of file emailgen.hpp.

◆ layers()

const std::vector< core::layer_info > & dasmig::emg::layers ( email_table which ) const

inline

The layers in effect for one table, in order.

Parameters

which The table.

Returns: The layer records.

Definition at line 437 of file emailgen.hpp.

◆ load() [1/2]

void dasmig::emg::load ( const std::filesystem::path & dir )

inline

Load data from a resource directory, replacing all data and layers loaded before.

The directory must contain countries.tsv; the other tables are read when present. A path without countries.tsv is ignored.

Parameters

dir	Directory such as `resources/lite`.

Exceptions

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

Definition at line 331 of file emailgen.hpp.

◆ load() [2/2]

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

inline

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

Uses the compiled-in copy when the library is built with DASMIG_EMAIL_EMBED, otherwise searches resources/, ../resources, email-generator/resources and ../email-generator/resources.

Parameters

tier The tier.

Returns: False when the tier was not found.

Exceptions

core::tsv_error If a file is malformed.

Definition at line 352 of file emailgen.hpp.

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

dasmig/emailgen.hpp

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ emg()

Member Function Documentation

◆ countries()

◆ country_count()

◆ data_hash()

◆ extend() [1/2]

◆ extend() [2/2]

◆ extend_from_string()

◆ for_each_email() [1/2]

◆ for_each_email() [2/2]

◆ get_email() [1/2]

◆ get_email() [2/2]

◆ get_email_batch() [1/2]

◆ get_email_batch() [2/2]

◆ has_country()

◆ has_data()

◆ instance()

◆ layers()

◆ load() [1/2]

◆ load() [2/2]