City generator that produces random cities from GeoNames data. More...

#include <citygen.hpp>

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

	cg (const cg &)=delete
	Not copyable.

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

	cg (cg &&)=default
	Move constructor.

cg &	operator= (cg &&)=default
	Move assignment.

	~cg ()=default
	Default destructor.

city	get_city ()
	Generate a random city.

city	get_city (std::uint64_t call_seed) const
	Generate a deterministic city using a specific seed.

city	get_city (const std::string &country)
	Generate a random city filtered by country code.

city	get_city (const std::string &country, std::uint64_t call_seed) const
	Generate a deterministic city filtered by country code.

cg &	weighted (bool enable)
	Set whether generation is population-weighted or uniform.

bool	weighted () const
	Query whether generation is population-weighted.

void	load_admin1 (const std::filesystem::path &path)
	Load admin1 code-to-name mappings from a GeoNames admin1CodesASCII.txt file.

std::string	resolve_admin1 (const std::string &country_code, const std::string &admin1_code) const
	Resolve an admin1 code to a human-readable name.

bool	has_admin1 () const
	Check whether admin1 name mappings have been loaded.

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

std::size_t	city_count () const
	Return the number of loaded cities.

void	load (const std::filesystem::path &tsv_path)
	Load city data from a TSV file.

bool	load (dataset tier)
	Load a specific dataset tier from a base resources directory.

Seeding
cg &	seed (std::uint64_t seed_value)
	Seed the internal random engine for deterministic sequences.

cg &	unseed ()
	Reseed the engine with a non-deterministic source.

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

Detailed Description

City generator that produces random cities from GeoNames data.

Generates cities using population-weighted random selection from GeoNames data. Larger cities are proportionally more likely to be selected, mirroring real-world population distributions.

Can be used as a singleton via instance() or constructed independently. Independent instances own their own data and random engine, making them safe for concurrent use without shared state.

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

Definition at line 139 of file citygen.hpp.

Constructor & Destructor Documentation

◆ cg()

dasmig::cg::cg ( )

default

Default constructor — creates an empty generator with no data.

Call load() to populate city data before generating.

Member Function Documentation

◆ city_count()

std::size_t dasmig::cg::city_count ( ) const

inline

Return the number of loaded cities.

Returns: City count.

Definition at line 381 of file citygen.hpp.

◆ get_city() [1/4]

city dasmig::cg::get_city ( )

inline

Generate a random city.

By default, selection is population-weighted. Call weighted(false) to switch to uniform random selection.

Returns: A city object with all GeoNames fields.

Exceptions

std::runtime_error If no city data has been loaded.

Definition at line 171 of file citygen.hpp.

◆ get_city() [2/4]

city dasmig::cg::get_city ( const std::string & country )

inline

Generate a random city filtered by country code.

Parameters

country ISO-3166 two-letter country code (e.g., "BR", "US").

Returns: A city object from the specified country.

Exceptions

std::runtime_error	If no city data has been loaded.
std::invalid_argument	If no cities match the country code.

Definition at line 210 of file citygen.hpp.

◆ get_city() [3/4]

city dasmig::cg::get_city	(	const std::string &	country,
		std::uint64_t	call_seed
	)		const

inline

Generate a deterministic city filtered by country code.

Parameters

country	ISO-3166 two-letter country code.
call_seed	Seed for reproducible results.

Returns: A city object from the specified country.

Exceptions

std::runtime_error	If no city data has been loaded.
std::invalid_argument	If no cities match the country code.

Definition at line 222 of file citygen.hpp.

◆ get_city() [4/4]

city dasmig::cg::get_city ( std::uint64_t call_seed ) const

inline

Generate a deterministic city using a specific seed.

Given the same loaded data and seed, this method always produces the same city. Retrieve the seed from a previous city via city::seed().

Parameters

call_seed Seed for reproducible results.

Returns: A city object with all GeoNames fields.

Exceptions

std::runtime_error If no city data has been loaded.

Definition at line 185 of file citygen.hpp.

◆ has_admin1()

bool dasmig::cg::has_admin1 ( ) const

inline

Check whether admin1 name mappings have been loaded.

Returns: true if at least one mapping is available.

Definition at line 367 of file citygen.hpp.

◆ has_data()

bool dasmig::cg::has_data ( ) const

inline

Check whether any city data has been loaded.

Returns: true if at least one city is available.

Definition at line 374 of file citygen.hpp.

◆ instance()

static cg & dasmig::cg::instance ( )

inlinestatic

Access the global singleton instance.

The singleton auto-probes common resource paths on first access. For independent generators (e.g., inside an entity-generator component), prefer constructing a separate cg instance.

Returns: Reference to the global cg instance.

Definition at line 159 of file citygen.hpp.

◆ load() [1/2]

void dasmig::cg::load ( const std::filesystem::path & tsv_path )

inline

Load city data from a TSV file.

Expects a tab-delimited file with a header row and 16 columns matching the GeoNames schema (as produced by scripts/prepare_geonames.py). Safe to call multiple times to add from different files.

Parameters

tsv_path Path to the TSV file.

Definition at line 394 of file citygen.hpp.

◆ load() [2/2]

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

inline

Load a specific dataset tier from a base resources directory.

Probes common base paths ("resources", "../resources", "city-generator/resources") and loads from the lite/ or full/ subfolder according to tier.

Parameters

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

Returns: true if a matching directory was found and loaded.

Definition at line 447 of file citygen.hpp.

◆ load_admin1()

void dasmig::cg::load_admin1 ( const std::filesystem::path & path )

inline

Load admin1 code-to-name mappings from a GeoNames admin1CodesASCII.txt file.

Each line has tab-separated fields: CC.CODE \t Name \t ASCII_Name \t GeoNameID

After loading, resolve_admin1() can translate raw admin1 codes into human-readable names. Safe to call multiple times.

Parameters

path	Path to admin1CodesASCII.txt.

Definition at line 311 of file citygen.hpp.

◆ resolve_admin1()

std::string dasmig::cg::resolve_admin1	(	const std::string &	country_code,
		const std::string &	admin1_code
	)		const

inline

Resolve an admin1 code to a human-readable name.

Looks up the combination of country_code and admin1_code (e.g., "US" + "CA" → "California") in the loaded admin1 mapping. Returns the raw code if no match is found.

Parameters

country_code	ISO-3166 two-letter country code.
admin1_code	GeoNames first-level administrative code.

Returns: The admin1 name, or the raw code if not mapped.

Definition at line 351 of file citygen.hpp.

◆ seed()

cg & dasmig::cg::seed ( std::uint64_t seed_value )

inline

Seed the internal random engine for deterministic sequences.

Subsequent get_city() calls (without an explicit seed) draw per-call seeds from this engine, producing a reproducible sequence.

Parameters

seed_value The seed value.

Returns: *this for chaining.

Definition at line 263 of file citygen.hpp.

◆ unseed()

cg & dasmig::cg::unseed ( )

inline

Reseed the engine with a non-deterministic source.

Subsequent get_city() calls will produce non-reproducible results.

Returns: *this for chaining.

Definition at line 273 of file citygen.hpp.

◆ weighted() [1/2]

bool dasmig::cg::weighted ( ) const

inline

Query whether generation is population-weighted.

Returns: true if weighted (default), false if uniform.

Definition at line 296 of file citygen.hpp.

◆ weighted() [2/2]

cg & dasmig::cg::weighted ( bool enable )

inline

Set whether generation is population-weighted or uniform.

When true (default), larger cities are proportionally more likely to be selected. When false, every city has an equal probability.

Parameters

enable true for weighted, false for uniform.

Returns: *this for chaining.

Definition at line 288 of file citygen.hpp.

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

dasmig/citygen.hpp

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ cg()

Member Function Documentation

◆ city_count()

◆ get_city() [1/4]

◆ get_city() [2/4]

◆ get_city() [3/4]

◆ get_city() [4/4]

◆ has_admin1()

◆ has_data()

◆ instance()

◆ load() [1/2]

◆ load() [2/2]

◆ load_admin1()

◆ resolve_admin1()

◆ seed()

◆ unseed()

◆ weighted() [1/2]

◆ weighted() [2/2]