Interest Generator: draws a person's religion, hobbies and favourite film, game, book and music genres. More...

#include <interestgen.hpp>

Public Types
enum class	table : std::uint8_t { religion , interests , affinity , age_bands , regions }
	The data tables. More...

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

	intg (const intg &)=delete
	Not copyable.

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

	intg (intg &&) noexcept=default
	Movable.

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

	~intg ()=default
	Destructor.

interest	get_interest (const interest_request &request)
	Generate a random interest for a request.

interest	get_interest (const interest_request &request, std::uint64_t call_seed) const
	Generate a deterministic interest for a request.

std::vector< interest >	get_interest_batch (const interest_request &request, const core::batch_options &options)
	Generate a batch of interest results from a seed drawn like get_interest() draws its own.

std::vector< interest >	get_interest_batch (const interest_request &request, const core::batch_options &options, std::uint64_t batch_seed) const
	Generate a batch of interest results, deterministically.

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

template<typename Sink >
void	for_each_interest (const interest_request &request, const core::batch_options &options, Sink &&sink)
	Stream a batch of interest results with a batch seed drawn like get_interest() draws its own.

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

std::size_t	country_count () const
	Return the number of countries with religion data.

std::size_t	item_count () const
	Return the number of hobbies and genres loaded, all kinds.

std::span< const religion_share >	shares (std::string_view cca2) const
	The religion shares loaded for a country.

const std::vector< std::string > &	unresolved () const
	Affinity rows whose target is neither an item key nor `class:` and an activity class that is loaded. They are ignored, so removing an item needs no other change; this lists them to catch misspelt names.

void	load (const std::filesystem::path &dir)
	Load 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 (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 (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 (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 intg &	instance ()
	Access the global singleton instance.

Detailed Description

Interest Generator: draws a person's religion, hobbies and favourite film, game, book and music genres.

The country (when not given) comes from the "country" stream of the call seed, the religion from "religion", and each kind of item from a stream of its own ("hobby", "film", "game", "book", "music"), so fields added later leave these unchanged. Output is identical on every compiler and platform (dasmig-core).

An item's weight for a person is its base weight multiplied by factors for the person's sex, age band, country (or else region) and religion group, for the item and for its activity class; a missing factor is 1. Items are drawn without replacement.

A country chosen at random is uniform over the countries loaded; the data has no population column. Pass a country chosen by country-generator for a population-weighted world.

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

Thread safety: Each instance is independent. Concurrent calls to get_interest() on the same instance require external synchronisation.

Definition at line 189 of file interestgen.hpp.

Member Enumeration Documentation

◆ table

enum class dasmig::intg::table : std::uint8_t

strong

The data tables.

Enumerator
religion	`religion.tsv`: key `country_code` and `religion`; group, weight, year, basis.
interests	`interests.tsv`: key `kind` and `key`; label, weight, class, category, tags, min_age, max_age.
affinity	`affinity.tsv`: key `target` (an item key, or `class:` and a class), `dimension` and `value`; factor, basis.
age_bands	`age_bands.tsv`: key `band`; min_age, max_age.
regions	`regions.tsv`: key `country_code`; region.

Definition at line 193 of file interestgen.hpp.

Constructor & Destructor Documentation

◆ intg()

dasmig::intg::intg ( )

inline

Default constructor — creates an empty generator with no data.

Definition at line 204 of file interestgen.hpp.

Member Function Documentation

◆ country_count()

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

inline

Return the number of countries with religion data.

Returns: The count.

Definition at line 335 of file interestgen.hpp.

◆ data_hash()

std::uint64_t dasmig::intg::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 495 of file interestgen.hpp.

◆ extend() [1/2]

void dasmig::intg::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 religion.tsv, interests.tsv, affinity.tsv, age_bands.tsv and regions.tsv; 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 430 of file interestgen.hpp.

◆ extend() [2/2]

const core::layer_info & dasmig::intg::extend	(	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 table). 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 461 of file interestgen.hpp.

◆ extend_from_string()

const core::layer_info & dasmig::intg::extend_from_string	(	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 478 of file interestgen.hpp.

◆ for_each_interest() [1/2]

template<typename Sink >

void dasmig::intg::for_each_interest	(	const interest_request &	request,
		const core::batch_options &	options,
		Sink &&	sink
	)

inline

Stream a batch of interest results with a batch seed drawn like get_interest() draws its own.

Template Parameters

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

Parameters

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

Definition at line 320 of file interestgen.hpp.

◆ for_each_interest() [2/2]

template<typename Sink >

void dasmig::intg::for_each_interest	(	const interest_request &	request,
		const core::batch_options &	options,
		std::uint64_t	batch_seed,
		Sink &&	sink
	)		const

inline

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

Generates the same items as get_interest_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, interest&)`; 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 305 of file interestgen.hpp.

◆ get_interest() [1/2]

interest dasmig::intg::get_interest ( const interest_request & request )

inline

Generate a random interest for a request.

Parameters

request Country, age, sex and counts. Use {} for defaults.

Returns: The interest.

Exceptions

std::runtime_error	If no data has been loaded.
std::invalid_argument	If the country has no data, or every share of it has weight 0 (or, with no country, no country has a positive weight).

Definition at line 232 of file interestgen.hpp.

◆ get_interest() [2/2]

interest dasmig::intg::get_interest	(	const interest_request &	request,
		std::uint64_t	call_seed
	)		const

inline

Generate a deterministic interest for a request.

Parameters

request	Country, age, sex and counts. Use `{}` for defaults.
call_seed	Seed; the same seed, request and data give the same interest, independent of prior calls. Does not touch the instance's random engine.

Returns: The interest.

Exceptions

std::runtime_error	If no data has been loaded.
std::invalid_argument	As for the unseeded overload.

Definition at line 245 of file interestgen.hpp.

◆ get_interest_batch() [1/2]

std::vector< interest > dasmig::intg::get_interest_batch	(	const interest_request &	request,
		const core::batch_options &	options
	)

inline

Generate a batch of interest results from a seed drawn like get_interest() draws its own.

Item i is get_interest(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 262 of file interestgen.hpp.

◆ get_interest_batch() [2/2]

std::vector< interest > dasmig::intg::get_interest_batch	(	const interest_request &	request,
		const core::batch_options &	options,
		std::uint64_t	batch_seed
	)		const

inline

Generate a batch of interest results, deterministically.

Item i is exactly get_interest(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 `interest`).
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 283 of file interestgen.hpp.

◆ has_data()

bool dasmig::intg::has_data ( ) const

inline

Check whether religion data has been loaded.

Returns: True when at least one religion row is loaded.

Definition at line 331 of file interestgen.hpp.

◆ instance()

static intg & dasmig::intg::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 217 of file interestgen.hpp.

◆ item_count()

std::size_t dasmig::intg::item_count ( ) const

inline

Return the number of hobbies and genres loaded, all kinds.

Returns: The count.

Definition at line 339 of file interestgen.hpp.

◆ layers()

const std::vector< core::layer_info > & dasmig::intg::layers ( table which ) const

inline

The layers in effect for one table, in order.

Parameters

which The table.

Returns: The layer records.

Definition at line 487 of file interestgen.hpp.

◆ load() [1/2]

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

inline

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

The directory must contain religion.tsv; the other tables are read when present (a missing one leaves its table empty, so a directory with only religion.tsv draws no hobbies or media). A path without religion.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 380 of file interestgen.hpp.

◆ load() [2/2]

bool dasmig::intg::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_INTEREST_EMBED, otherwise searches resources/, ../resources, interest-generator/resources and ../interest-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 402 of file interestgen.hpp.

◆ shares()

std::span< const religion_share > dasmig::intg::shares ( std::string_view cca2 ) const

inline

The religion shares loaded for a country.

Parameters

cca2	ISO 3166-1 alpha-2 country code.

Returns: The shares in table order; empty when the country has none.

Definition at line 349 of file interestgen.hpp.

◆ unresolved()

const std::vector< std::string > & dasmig::intg::unresolved ( ) const

inline

Affinity rows whose target is neither an item key nor class: and an activity class that is loaded. They are ignored, so removing an item needs no other change; this lists them to catch misspelt names.

Returns: One description per ignored row, such as ‘affinity.tsv:12: unknown target 'footbal’`.

Definition at line 362 of file interestgen.hpp.

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

dasmig/interestgen.hpp

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ table

Constructor & Destructor Documentation

◆ intg()

Member Function Documentation

◆ country_count()

◆ data_hash()

◆ extend() [1/2]

◆ extend() [2/2]

◆ extend_from_string()

◆ for_each_interest() [1/2]

◆ for_each_interest() [2/2]

◆ get_interest() [1/2]

◆ get_interest() [2/2]

◆ get_interest_batch() [1/2]

◆ get_interest_batch() [2/2]

◆ has_data()

◆ instance()

◆ item_count()

◆ layers()

◆ load() [1/2]

◆ load() [2/2]

◆ shares()

◆ unresolved()