Phone Generator: phone numbers valid in each country's numbering plan. More...

#include <phonegen.hpp>

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

	phg (const phg &)=delete
	Not copyable.

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

	phg (phg &&) noexcept=default
	Movable.

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

	~phg ()=default
	Destructor.

phone	get_phone (const phone_request &request)
	Generate a random phone number. Use phone_request{} for the defaults.

phone	get_phone (const phone_request &request, std::uint64_t call_seed) const
	Generate a deterministic phone number.

std::vector< phone >	get_phone_batch (const phone_request &request, const core::batch_options &options)
	Generate a batch of phone results from a seed drawn like get_phone() draws its own.

std::vector< phone >	get_phone_batch (const phone_request &request, const core::batch_options &options, std::uint64_t batch_seed) const
	Generate a batch of phone results, deterministically.

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

template<typename Sink >
void	for_each_phone (const phone_request &request, const core::batch_options &options, Sink &&sink)
	Stream a batch of phone results with a batch seed drawn like get_phone() 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 that have numbers.

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

bool	has_country (std::string_view country) const
	Whether numbers can be generated for a country.

bool	has_reserved (std::string_view country, phone_type type) const
	Whether a country has a range set aside for fiction.

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 (phone_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 (phone_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 (phone_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 phg &	instance ()
	Access the global singleton instance.

Detailed Description

Phone Generator: phone numbers valid in each country's numbering plan.

A call draws a country (by population), a type, a range of that country (by weight: even over the numbers of a length) and the remaining digits, each from a stream split from the call seed ("country", "phone-type", "phone-range", "phone-digits"). 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 241 of file phonegen.hpp.

Constructor & Destructor Documentation

◆ phg()

dasmig::phg::phg ( )

inline

Default constructor — creates an empty generator with no data.

Definition at line 246 of file phonegen.hpp.

Member Function Documentation

◆ countries()

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

inline

The countries a number 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 402 of file phonegen.hpp.

◆ country_count()

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

inline

Return the number of countries that have numbers.

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

Definition at line 397 of file phonegen.hpp.

◆ data_hash()

std::uint64_t dasmig::phg::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 548 of file phonegen.hpp.

◆ extend() [1/2]

void dasmig::phg::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 phone_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 483 of file phonegen.hpp.

◆ extend() [2/2]

const core::layer_info & dasmig::phg::extend	(	phone_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 514 of file phonegen.hpp.

◆ extend_from_string()

const core::layer_info & dasmig::phg::extend_from_string	(	phone_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 531 of file phonegen.hpp.

◆ for_each_phone() [1/2]

template<typename Sink >

void dasmig::phg::for_each_phone	(	const phone_request &	request,
		const core::batch_options &	options,
		Sink &&	sink
	)

inline

Stream a batch of phone results with a batch seed drawn like get_phone() draws its own.

Template Parameters

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

Parameters

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

Definition at line 384 of file phonegen.hpp.

◆ for_each_phone() [2/2]

template<typename Sink >

void dasmig::phg::for_each_phone	(	const phone_request &	request,
		const core::batch_options &	options,
		std::uint64_t	batch_seed,
		Sink &&	sink
	)		const

inline

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

Generates the same items as get_phone_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, phone&)`; 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 369 of file phonegen.hpp.

◆ get_phone() [1/2]

phone dasmig::phg::get_phone ( const phone_request & request )

inline

Generate a random phone number. Use phone_request{} for the defaults.

Parameters

request What to generate.

Returns: The phone number.

Exceptions

std::runtime_error	If no data has been loaded.
std::invalid_argument	If the country is unknown or has no number of the requested type.

Definition at line 274 of file phonegen.hpp.

◆ get_phone() [2/2]

phone dasmig::phg::get_phone	(	const phone_request &	request,
		std::uint64_t	call_seed
	)		const

inline

Generate a deterministic phone number.

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 phone number.

Exceptions

std::runtime_error	If no data has been loaded.
std::invalid_argument	If the country is unknown or has no number of the requested type.

Definition at line 287 of file phonegen.hpp.

◆ get_phone_batch() [1/2]

std::vector< phone > dasmig::phg::get_phone_batch	(	const phone_request &	request,
		const core::batch_options &	options
	)

inline

Generate a batch of phone results from a seed drawn like get_phone() draws its own.

Item i is get_phone(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 326 of file phonegen.hpp.

◆ get_phone_batch() [2/2]

std::vector< phone > dasmig::phg::get_phone_batch	(	const phone_request &	request,
		const core::batch_options &	options,
		std::uint64_t	batch_seed
	)		const

inline

Generate a batch of phone results, deterministically.

Item i is exactly get_phone(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 `phone`).
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 347 of file phonegen.hpp.

◆ has_country()

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

inline

Whether numbers can be generated for a country.

Parameters

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

Returns: True when the country is in countries() (it is loaded and has at least one range).

Definition at line 407 of file phonegen.hpp.

◆ has_data()

bool dasmig::phg::has_data ( ) const

inline

Check whether any data has been loaded.

Returns: True when at least one country is loaded.

Definition at line 393 of file phonegen.hpp.

◆ has_reserved()

bool dasmig::phg::has_reserved	(	std::string_view	country,
		phone_type	type
	)		const

inline

Whether a country has a range set aside for fiction.

Parameters

country	ISO-3166 two-letter code (any case).
type	Mobile or fixed line.

Returns: True when safe numbers of that type are reserved ones.

Definition at line 419 of file phonegen.hpp.

◆ instance()

static phg & dasmig::phg::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 259 of file phonegen.hpp.

◆ layers()

const std::vector< core::layer_info > & dasmig::phg::layers ( phone_table which ) const

inline

The layers in effect for one table, in order.

Parameters

which The table.

Returns: The layer records.

Definition at line 540 of file phonegen.hpp.

◆ load() [1/2]

void dasmig::phg::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 435 of file phonegen.hpp.

◆ load() [2/2]

bool dasmig::phg::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_PHONE_EMBED, otherwise searches resources/, ../resources, phone-generator/resources and ../phone-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 456 of file phonegen.hpp.

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

dasmig/phonegen.hpp

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ phg()

Member Function Documentation

◆ countries()

◆ country_count()

◆ data_hash()

◆ extend() [1/2]

◆ extend() [2/2]

◆ extend_from_string()

◆ for_each_phone() [1/2]

◆ for_each_phone() [2/2]

◆ get_phone() [1/2]

◆ get_phone() [2/2]

◆ get_phone_batch() [1/2]

◆ get_phone_batch() [2/2]

◆ has_country()

◆ has_data()

◆ has_reserved()

◆ instance()

◆ layers()

◆ load() [1/2]

◆ load() [2/2]