Bidirectional name↔index registry for SWMM objects. More...

#include <NameIndex.hpp>

Collaboration diagram for openswmm::NameIndex:

Public Member Functions
	NameIndex ()=default
	Create an empty registry with no deferred-removal scope.

int	add (const std::string &name)
	Copy a new name and assign the next sequential index.

int	try_add (const std::string &name)
	Copy a new name, returning a duplicate sentinel instead of a duplicate exception.

int	find (std::string_view name) const noexcept
	Look up a borrowed name without allocating a temporary key.

std::optional< int >	try_find (std::string_view name) const noexcept
	Look up a borrowed name with an optional result.

const std::string *	canonical (std::string_view name) const noexcept
	Borrow the original spelling of an equivalent registry key.

const std::string &	name_of (int idx) const
	Borrow a registered name by its ordered index.

int	size () const noexcept
	Count names in the ordered vector.

bool	empty () const noexcept
	Test whether the ordered name vector is empty.

void	reserve (std::size_t n)
	Request capacity for the map and ordered name vector.

void	clear () noexcept
	Erase all names and map entries.

void	pop_back () noexcept
	Remove the most recently ordered name without renumbering earlier rows.

bool	rename (int idx, const std::string &newName) noexcept
	Replace one name while retaining its numeric index.

void	remove_at (int idx) noexcept
	Erase an ordered name and renumber following indices.

void	begin_bulk_remove () noexcept
	Enter a nestable scope that defers hash-map rebuilding.

void	end_bulk_remove ()
	Close one deferred-removal scope and rebuild on the outermost close.

const std::vector< std::string > &	names () const noexcept
	Borrow ordered stored spellings.

Detailed Description

Bidirectional name↔index registry for SWMM objects.

Maintains both a hash map (name→index) and a vector (index→name) so that either direction of lookup is O(1).

Lookups are CASE-INSENSITIVE (ASCII fold), matching the legacy engine's hash table (src/legacy/engine/hash.c UCHAR). Names are stored with their original spelling — name_of()/names() feed the .out ID tables, interface files, and the .inp/GeoPackage writers, which must round-trip the user's spelling byte-identically. Two names differing only in case are therefore the SAME entry; add() treats them as duplicates, exactly as legacy does.

Constructor & Destructor Documentation

◆ NameIndex()

openswmm::NameIndex::NameIndex ( )

default

Create an empty registry with no deferred-removal scope.

Member Function Documentation

◆ add()

int openswmm::NameIndex::add ( const std::string & name )

inline

Copy a new name and assign the next sequential index.

Caller serializes mutation and lookup, and keeps size representable as int. Invalidates vector-backed name views if insertion reallocates.

Exceptions

std::invalid_argument	When an equivalent name already exists.
std::bad_alloc	On allocation; insertion is not strongly transactional if the map insert succeeds before the ordered-name append fails.

Parameters

[in] name Borrowed name, matched by ASCII-insensitive byte comparison; empty names are accepted.

Returns: Index equal to the old size().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ begin_bulk_remove()

void openswmm::NameIndex::begin_bulk_remove ( )

inlinenoexcept

Enter a nestable scope that defers hash-map rebuilding.

While any scope is active, only ordered-vector access/removal is valid; do not use find, try_find, canonical, rename, insertion or map-dependent pop_back. Must pair with end_bulk_remove(), including on exceptional paths. Caller serializes access.

◆ canonical()

const std::string * openswmm::NameIndex::canonical ( std::string_view name ) const

inlinenoexcept

Borrow the original spelling of an equivalent registry key.

Pointer can be invalidated by name-vector insertion, reserve, rename, erasure or clear. Do not call while a bulk-removal scope has made map indices stale.

Parameters

[in] name Borrowed name, matched by ASCII-insensitive byte comparison; empty names are accepted.

Returns: Pointer into names_, or nullptr for no match; do not free.

Here is the caller graph for this function:

◆ clear()

void openswmm::NameIndex::clear ( )

inlinenoexcept

Erase all names and map entries.

Invalidates borrowed names. Does not reset bulk_depth_; callers must still balance any active begin/end scope.

◆ empty()

bool openswmm::NameIndex::empty ( ) const

inlinenoexcept

Test whether the ordered name vector is empty.

Returns: True when no names remain, including during deferred removal.

◆ end_bulk_remove()

void openswmm::NameIndex::end_bulk_remove ( )

inline

Close one deferred-removal scope and rebuild on the outermost close.

Unbalanced close is ignored. Outermost close rebuilds the entire map; allocation exceptions propagate and can leave a partial map after the nesting depth has returned to zero.

◆ find()

int openswmm::NameIndex::find ( std::string_view name ) const

inlinenoexcept

Look up a borrowed name without allocating a temporary key.

Not valid while a bulk-removal scope has left the hash map stale.

Parameters

[in] name Borrowed name, matched by ASCII-insensitive byte comparison; empty names are accepted.

Returns: Existing zero-based index, or -1 when absent.

◆ name_of()

const std::string & openswmm::NameIndex::name_of ( int idx ) const

inline

Borrow a registered name by its ordered index.

Works during deferred removal because the ordered vector stays current.

Exceptions

std::out_of_range When idx is not an existing row.

Parameters

[in] idx Zero-based index in [0,size()); negative values fail the vector bounds check.

Returns: Reference into names_, invalidated by relevant vector mutations or registry destruction.

Here is the caller graph for this function:

◆ names()

const std::vector< std::string > & openswmm::NameIndex::names ( ) const

inlinenoexcept

Borrow ordered stored spellings.

Ordered access remains current while bulk map rebuilding is deferred.

Returns: Owned vector reference; element references/views require no intervening invalidating mutation.

Here is the caller graph for this function:

◆ pop_back()

void openswmm::NameIndex::pop_back ( )

inlinenoexcept

Remove the most recently ordered name without renumbering earlier rows.

Empty is a no-op. Caller must not use this while map indices are stale from deferred removal. Copies the tail key before erasing; because this function is noexcept, allocation failure in that copy terminates.

◆ remove_at()

void openswmm::NameIndex::remove_at ( int idx )

inlinenoexcept

Erase an ordered name and renumber following indices.

Within a bulk scope erases only names_, leaving the map stale. Outside a scope clears/rebuilds the map. Does not repair any model object references or enforce lifecycle. noexcept means allocation failure during rebuild terminates.

Parameters

[in] idx Zero-based ordered index; out-of-range is a no-op.

Here is the caller graph for this function:

◆ rename()

bool openswmm::NameIndex::rename	(	int	idx,
		const std::string &	newName )

inlinenoexcept

Replace one name while retaining its numeric index.

Do not call during deferred removal. Borrowed names may be invalidated; no lifecycle validation is performed. This noexcept function can allocate during string/map replacement; allocation failure terminates.

Parameters

[in]	idx	Existing ordered index; invalid values return false without mutation.
[in]	newName	Copied replacement token; empty is accepted, case-only respelling allowed, collision with another row refused.

Returns: True after replacement; false for invalid idx or collision.

Here is the caller graph for this function:

◆ reserve()

void openswmm::NameIndex::reserve ( std::size_t n )

inline

Request capacity for the map and ordered name vector.

Can rehash the map and reallocate names_, invalidating map iterators/name references. Allocation exceptions propagate.

Parameters

[in] n Expected name count; no elements are inserted.

Here is the caller graph for this function:

◆ size()

int openswmm::NameIndex::size ( ) const

inlinenoexcept

Count names in the ordered vector.

Returns: Ordered-name count converted to int; callers keep the count representable.

Here is the caller graph for this function:

◆ try_add()

int openswmm::NameIndex::try_add ( const std::string & name )

inline

Copy a new name, returning a duplicate sentinel instead of a duplicate exception.

Allocation exceptions still propagate; this function is not noexcept. Map insertion precedes ordered-vector append, so an allocation failure in the latter can leave stores inconsistent. Caller serializes access and keeps size representable as int.

Parameters

[in] name Borrowed name, matched by ASCII-insensitive byte comparison; empty names are accepted.

Returns: New index, or -1 for an equivalent existing name.

Here is the caller graph for this function:

◆ try_find()

std::optional< int > openswmm::NameIndex::try_find ( std::string_view name ) const

inlinenoexcept

Look up a borrowed name with an optional result.

Not valid while bulk removal defers map rebuild.

Parameters

[in] name Borrowed name, matched by ASCII-insensitive byte comparison; empty names are accepted.

Returns: Existing index or std::nullopt when absent.

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

/home/runner/work/openswmm.engine/openswmm.engine/src/engine/data/NameIndex.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ NameIndex()

Member Function Documentation

◆ add()

◆ begin_bulk_remove()

◆ canonical()

◆ clear()

◆ empty()

◆ end_bulk_remove()

◆ find()

◆ name_of()

◆ names()

◆ pop_back()

◆ remove_at()

◆ rename()

◆ reserve()

◆ size()

◆ try_add()

◆ try_find()