dasmig::adg Class Reference

Address Generator: postal addresses with real streets by place. More...

#include <addressgen.hpp>

Public Member Functions
	adg ()
	Default constructor — creates an empty generator with no data.
	adg (const adg &)=delete
	Not copyable.
adg &	operator= (const adg &)=delete
	Not copyable.
	adg (adg &&) noexcept=default
	Movable.
adg &	operator= (adg &&) noexcept=default
	Movable.
	~adg ()=default
	Destructor.
address	get_address (const address_request &request)
	Generate a random address. Use address_request{} for the defaults.
address	get_address (const address_request &request, std::uint64_t call_seed) const
	Generate a deterministic address.
street	get_street (const street_request &request)
	Generate a random street. Use street_request{} for the defaults.
street	get_street (const street_request &request, std::uint64_t call_seed) const
	Generate a deterministic street.
std::vector< street >	get_street_batch (const street_request &request, const core::batch_options &options)
	Generate a batch of streets from a seed drawn like get_street() draws its own.
std::vector< street >	get_street_batch (const street_request &request, const core::batch_options &options, std::uint64_t batch_seed) const
	Generate a batch of streets, deterministically.
template<typename Sink >
void	for_each_street (const street_request &request, const core::batch_options &options, std::uint64_t batch_seed, Sink &&sink) const
	Stream a batch of streets to a sink without holding the whole batch.
template<typename Sink >
void	for_each_street (const street_request &request, const core::batch_options &options, Sink &&sink)
	Stream a batch of streets with a batch seed drawn like get_street() draws its own.
std::string	get_postcode (const postcode_request &request)
	Generate a random postcode in the country's format. Use postcode_request{} for the defaults.
std::string	get_postcode (const postcode_request &request, std::uint64_t call_seed) const
	Generate a deterministic postcode.
std::vector< std::string >	get_postcode_batch (const postcode_request &request, const core::batch_options &options)
	Generate a batch of postcodes from a seed drawn like get_postcode() draws its own.
std::vector< std::string >	get_postcode_batch (const postcode_request &request, const core::batch_options &options, std::uint64_t batch_seed) const
	Generate a batch of postcodes, deterministically.
template<typename Sink >
void	for_each_postcode (const postcode_request &request, const core::batch_options &options, std::uint64_t batch_seed, Sink &&sink) const
	Stream a batch of postcodes to a sink without holding the whole batch.
template<typename Sink >
void	for_each_postcode (const postcode_request &request, const core::batch_options &options, Sink &&sink)
	Stream a batch of postcodes with a batch seed drawn like get_postcode() draws its own.
std::vector< address >	get_address_batch (const address_request &request, const core::batch_options &options)
	Generate a batch of address results from a seed drawn like get_address() draws its own.
std::vector< address >	get_address_batch (const address_request &request, const core::batch_options &options, std::uint64_t batch_seed) const
	Generate a batch of address results, deterministically.
template<typename Sink >
void	for_each_address (const address_request &request, const core::batch_options &options, std::uint64_t batch_seed, Sink &&sink) const
	Stream a batch of address results to a sink without holding the whole batch.
template<typename Sink >
void	for_each_address (const address_request &request, const core::batch_options &options, Sink &&sink)
	Stream a batch of address results with a batch seed drawn like get_address() draws its own.
bool	has_data () const
	Check whether any data has been loaded.
std::size_t	place_count () const
	Return the number of loaded places.
std::size_t	country_count () const
	Return the number of countries that have places.
const std::vector< std::string > &	countries () const
	The countries that have places, sorted.
bool	has_streets (std::string_view code) const
	Whether a country has real streets for at least one place.
bool	load_streets (std::string_view code) const
	Load the street data of one country now, instead of on the first call that needs it.
bool	streets_loaded (std::string_view code) const
	Whether a country's street data is in memory.
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 (address_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 (address_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 (address_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 adg &	instance ()
	Access the global singleton instance.

Detailed Description

Address Generator: postal addresses with real streets by place.

A call draws a country (by population), a place in it (by population), a street of that place (by address count), a house number, a unit and a postcode, each from a stream split from the call seed ("country", "place", "street", "number", "unit", "postcode"), and lays the address out in the country's order. Places without street data get a composed street. 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_address(request, seed) on the same instance are safe, including the first read of a full country's street file; calls that use the instance engine, loading and extending require external synchronisation.

Definition at line 311 of file addressgen.hpp.

Constructor & Destructor Documentation

adg()

dasmig::adg::adg ( )

inline

Default constructor — creates an empty generator with no data.

Definition at line 316 of file addressgen.hpp.

Member Function Documentation

countries()

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

inline

The countries that have places, sorted.

Returns

ISO codes.

Definition at line 671 of file addressgen.hpp.

country_count()

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

inline

Return the number of countries that have places.

Returns

The count.

Definition at line 667 of file addressgen.hpp.

data_hash()

std::uint64_t dasmig::adg::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 849 of file addressgen.hpp.

extend() [1/2]

const core::layer_info & dasmig::adg::extend ( address_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 815 of file addressgen.hpp.

extend() [2/2]

void dasmig::adg::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 address_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 784 of file addressgen.hpp.

extend_from_string()

const core::layer_info & dasmig::adg::extend_from_string ( address_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 832 of file addressgen.hpp.

for_each_address() [1/2]

template<typename Sink >

void dasmig::adg::for_each_address ( const address_request &  request, const core::batch_options &  options, Sink &&  sink  )

inline

Stream a batch of address results with a batch seed drawn like get_address() draws its own.

Template Parameters

Sink	Callable taking (std::uint64_t, address&).

Parameters

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

Definition at line 649 of file addressgen.hpp.

for_each_address() [2/2]

template<typename Sink >

void dasmig::adg::for_each_address ( const address_request &  request, const core::batch_options &  options, std::uint64_t  batch_seed, Sink &&  sink  ) const

inline

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

Generates the same items as get_address_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, address&); 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 634 of file addressgen.hpp.

for_each_postcode() [1/2]

template<typename Sink >

void dasmig::adg::for_each_postcode ( const postcode_request &  request, const core::batch_options &  options, Sink &&  sink  )

inline

Stream a batch of postcodes with a batch seed drawn like get_postcode() draws its own.

Template Parameters

Sink	Callable taking (std::uint64_t, std::string&).

Parameters

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

Definition at line 575 of file addressgen.hpp.

for_each_postcode() [2/2]

template<typename Sink >

void dasmig::adg::for_each_postcode ( const postcode_request &  request, const core::batch_options &  options, std::uint64_t  batch_seed, Sink &&  sink  ) const

inline

Stream a batch of postcodes to a sink without holding the whole batch.

Template Parameters

Sink	Callable taking (std::uint64_t, std::string&).

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, in index order, on the calling thread.

Definition at line 561 of file addressgen.hpp.

for_each_street() [1/2]

template<typename Sink >

void dasmig::adg::for_each_street ( const street_request &  request, const core::batch_options &  options, Sink &&  sink  )

inline

Stream a batch of streets with a batch seed drawn like get_street() draws its own.

Template Parameters

Sink	Callable taking (std::uint64_t, street&).

Parameters

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

Definition at line 493 of file addressgen.hpp.

for_each_street() [2/2]

template<typename Sink >

void dasmig::adg::for_each_street ( const street_request &  request, const core::batch_options &  options, std::uint64_t  batch_seed, Sink &&  sink  ) const

inline

Stream a batch of streets to a sink without holding the whole batch.

Template Parameters

Sink	Callable taking (std::uint64_t, street&).

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, in index order, on the calling thread.

Definition at line 479 of file addressgen.hpp.

get_address() [1/2]

address dasmig::adg::get_address ( const address_request &  request )

inline

Generate a random address. Use address_request{} for the defaults.

Parameters

request

What to generate.

Returns

The address.

Exceptions

std::runtime_error	If no data has been loaded.
std::invalid_argument	If the request names an unknown country or place.

Definition at line 344 of file addressgen.hpp.

get_address() [2/2]

address dasmig::adg::get_address ( const address_request &  request, std::uint64_t  call_seed  ) const

inline

Generate a deterministic 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 data has been loaded.
std::invalid_argument	If the request names an unknown country or place.

Definition at line 357 of file addressgen.hpp.

get_address_batch() [1/2]

std::vector< address > dasmig::adg::get_address_batch ( const address_request &  request, const core::batch_options &  options  )

inline

Generate a batch of address results from a seed drawn like get_address() draws its own.

Item i is get_address(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 591 of file addressgen.hpp.

get_address_batch() [2/2]

std::vector< address > dasmig::adg::get_address_batch ( const address_request &  request, const core::batch_options &  options, std::uint64_t  batch_seed  ) const

inline

Generate a batch of address results, deterministically.

Item i is exactly get_address(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 address).
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 612 of file addressgen.hpp.

get_postcode() [1/2]

std::string dasmig::adg::get_postcode ( const postcode_request &  request )

inline

Generate a random postcode in the country's format. Use postcode_request{} for the defaults.

Parameters

request

What to generate.

Returns

The postcode; empty for a country without postcodes.

Exceptions

std::runtime_error	If no data has been loaded.
std::invalid_argument	If the request names an unknown country or place.

Definition at line 504 of file addressgen.hpp.

get_postcode() [2/2]

std::string dasmig::adg::get_postcode ( const postcode_request &  request, std::uint64_t  call_seed  ) const

inline

Generate a deterministic postcode.

Draws from the same streams as get_address(), so for the same request fields and seed it is the postcode of that address.

Parameters

request	What to generate.
call_seed	Seed; does not touch the instance engine.

Returns

The postcode; empty for a country without postcodes.

Exceptions

std::runtime_error	If no data has been loaded.
std::invalid_argument	If the request names an unknown country or place.

Definition at line 519 of file addressgen.hpp.

get_postcode_batch() [1/2]

std::vector< std::string > dasmig::adg::get_postcode_batch ( const postcode_request &  request, const core::batch_options &  options  )

inline

Generate a batch of postcodes from a seed drawn like get_postcode() 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 532 of file addressgen.hpp.

get_postcode_batch() [2/2]

std::vector< std::string > dasmig::adg::get_postcode_batch ( const postcode_request &  request, const core::batch_options &  options, std::uint64_t  batch_seed  ) const

inline

Generate a batch of postcodes, deterministically.

Item i is get_postcode(request, core::item_seed(batch_seed, options.first + i)).

Parameters

request	What every item is generated from.
options	Count, first index, threads and uniqueness (a rule made for std::string).
batch_seed	Seed of the whole batch.

Returns

The results, in index order.

Definition at line 546 of file addressgen.hpp.

get_street() [1/2]

street dasmig::adg::get_street ( const street_request &  request )

inline

Generate a random street. Use street_request{} for the defaults.

Parameters

request

What to generate.

Returns

The street.

Exceptions

std::runtime_error	If no data has been loaded.
std::invalid_argument	If the request names an unknown country or place.

Definition at line 414 of file addressgen.hpp.

get_street() [2/2]

street dasmig::adg::get_street ( const street_request &  request, std::uint64_t  call_seed  ) const

inline

Generate a deterministic street.

Draws from the same streams as get_address(), so for the same request fields and seed it is the street of that address.

Parameters

request	What to generate.
call_seed	Seed; does not touch the instance engine.

Returns

The street.

Exceptions

std::runtime_error	If no data has been loaded.
std::invalid_argument	If the request names an unknown country or place.

Definition at line 429 of file addressgen.hpp.

get_street_batch() [1/2]

std::vector< street > dasmig::adg::get_street_batch ( const street_request &  request, const core::batch_options &  options  )

inline

Generate a batch of streets from a seed drawn like get_street() 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 450 of file addressgen.hpp.

get_street_batch() [2/2]

std::vector< street > dasmig::adg::get_street_batch ( const street_request &  request, const core::batch_options &  options, std::uint64_t  batch_seed  ) const

inline

Generate a batch of streets, deterministically.

Item i is get_street(request, core::item_seed(batch_seed, options.first + i)).

Parameters

request	What every item is generated from.
options	Count, first index, threads and uniqueness (a rule made for street).
batch_seed	Seed of the whole batch.

Returns

The results, in index order.

Definition at line 464 of file addressgen.hpp.

has_data()

bool dasmig::adg::has_data ( ) const

inline

Check whether any data has been loaded.

Returns

True when places are loaded.

Definition at line 659 of file addressgen.hpp.

has_streets()

bool dasmig::adg::has_streets ( std::string_view  code ) const

inline

Whether a country has real streets for at least one place.

Parameters

code	ISO 3166-1 alpha-2.

Returns

True when street data is loaded for the country.

Definition at line 676 of file addressgen.hpp.

instance()

static adg & dasmig::adg::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 329 of file addressgen.hpp.

layers()

const std::vector< core::layer_info > & dasmig::adg::layers ( address_table  which ) const

inline

The layers in effect for one table, in order.

Parameters

which

The table.

Returns

The layer records.

Definition at line 841 of file addressgen.hpp.

load() [1/2]

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

inline

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

The directory must contain places.tsv; the other tables are read when present. A path without places.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 720 of file addressgen.hpp.

load() [2/2]

bool dasmig::adg::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_ADDRESS_EMBED, otherwise searches resources/, ../resources, address-generator/resources and ../address-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 748 of file addressgen.hpp.

load_streets()

bool dasmig::adg::load_streets ( std::string_view  code ) const

inline

Load the street data of one country now, instead of on the first call that needs it.

Only the full tier keeps its streets in one file per country; for the other data this does nothing. Safe to call from several threads.

Parameters

code	ISO 3166-1 alpha-2.

Returns

True when the country has real streets.

Exceptions

std::runtime_error	If the country's file is missing or does not match streets.manifest.tsv.
core::tsv_error	If the file is malformed.

Definition at line 693 of file addressgen.hpp.

place_count()

std::size_t dasmig::adg::place_count ( ) const

inline

Return the number of loaded places.

Returns

The count.

Definition at line 663 of file addressgen.hpp.

streets_loaded()

bool dasmig::adg::streets_loaded ( std::string_view  code ) const

inline

Whether a country's street data is in memory.

Parameters

code	ISO 3166-1 alpha-2.

Returns

True for the lite data (always loaded) and for a full country once a call or load_streets() has read its file.

Definition at line 704 of file addressgen.hpp.

---

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

• dasmig/addressgen.hpp