openswmm::NameIndex Class Reference

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

#include <NameIndex.hpp>

Collaboration diagram for openswmm::NameIndex:

Public Member Functions
	NameIndex ()=default
int	add (const std::string &name)
	Add a new name and assign the next sequential index.
int	try_add (const std::string &name)
	Non-throwing add.
int	find (std::string_view name) const noexcept
	Look up the index for a name (case-insensitive).
std::optional< int >	try_find (std::string_view name) const noexcept
	Look up the index (case-insensitive), returning std::optional.
const std::string *	canonical (std::string_view name) const noexcept
	Stored (original) spelling for a case-insensitive match.
const std::string &	name_of (int idx) const
	Return the name for a given index.
int	size () const noexcept
	Number of registered names.
bool	empty () const noexcept
	True if no names are registered.
void	reserve (std::size_t n)
	Pre-allocate for a known count (avoids rehash during input).
void	clear () noexcept
	Remove all entries.
void	pop_back () noexcept
	Pop the tail entry — the name added most recently.
bool	rename (int idx, const std::string &newName) noexcept
	Rename the entry at idx to newName.
void	remove_at (int idx) noexcept
	Remove the entry at idx and rebuild the name→index map.
void	begin_bulk_remove () noexcept
	Defer map rebuilds across a batch of remove_at() calls.
void	end_bulk_remove ()
	Close a begin_bulk_remove() scope; outermost close rebuilds the map once. Unbalanced calls are ignored.
const std::vector< std::string > &	names () const noexcept
	Read-only access to the ordered name list.

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

Member Function Documentation

add()

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

inline

Add a new name and assign the next sequential index.

Parameters

name	Object name (stored as-is; matched case-insensitively).

Returns

Assigned index (== size() before this call).

Exceptions

std::invalid_argument

if name is already registered (any case spelling). Callers on user-input paths should prefer try_add() and report the duplicate themselves.

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

Defer map rebuilds across a batch of remove_at() calls.

Between begin and end the name→index MAP is stale: find(), try_find(), canonical() and rename() must not be used (the index→name direction — name_of()/names()/size() — stays exact throughout). Nestable; the outermost end rebuilds. ObjectDeleter's delete_*_many are the intended callers and are audited to perform no map lookups while deferred.

canonical()

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

inlinenoexcept

Stored (original) spelling for a case-insensitive match.

Parameters

name	Object name in any case spelling.

Returns

Pointer to the registered spelling, or nullptr if the name is not registered. Used by duplicate-ID diagnostics to report both spellings.

Here is the caller graph for this function:

clear()

void openswmm::NameIndex::clear ( )

inlinenoexcept

Remove all entries.

empty()

bool openswmm::NameIndex::empty ( ) const

inlinenoexcept

True if no names are registered.

end_bulk_remove()

void openswmm::NameIndex::end_bulk_remove ( )

inline

Close a begin_bulk_remove() scope; outermost close rebuilds the map once. Unbalanced calls are ignored.

find()

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

inlinenoexcept

Look up the index for a name (case-insensitive).

Parameters

name	Object name.

Returns

Index, or -1 if not found.

Here is the caller graph for this function:

name_of()

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

inline

Return the name for a given index.

Exceptions

std::out_of_range

if idx is out of bounds.

Here is the caller graph for this function:

names()

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

inlinenoexcept

Read-only access to the ordered name list.

Here is the caller graph for this function:

pop_back()

void openswmm::NameIndex::pop_back ( )

inlinenoexcept

Pop the tail entry — the name added most recently.

Used by the C ABI's *_pop_last family to undo a just-added object without requiring the full renumbering that a general-purpose remove_at(idx) would need. No-op when empty.

remove_at()

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

inlinenoexcept

Remove the entry at idx and rebuild the name→index map.

All entries at indices > idx are shifted down by one. The map is rebuilt from scratch — O(n) — which is acceptable since this is only called in BUILDING or OPENED state. No-op if idx is out of range.

Inside a begin_bulk_remove()/end_bulk_remove() scope only the vector entry is erased (index→name stays exact) and the ONE rebuild happens at scope end — deleting K objects then costs one rehash instead of K. That per-delete rehash was the dominant bulk-delete cost on large models (BULK_DELETE_AND_WINDOWS_OPEN_PERF_PLAN_2026-09-01 Phase A1).

Here is the caller graph for this function:

rename()

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

inlinenoexcept

Rename the entry at idx to newName.

Parameters

idx	Index of the entry to rename.
newName	New name (must not collide, case-insensitively, with a DIFFERENT entry; a pure case-respelling of the same entry is allowed).

Returns

true on success; false if idx is out of range or newName is already in use by another entry.

Here is the caller graph for this function:

reserve()

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

inline

Pre-allocate for a known count (avoids rehash during input).

Here is the caller graph for this function:

size()

int openswmm::NameIndex::size ( ) const

inlinenoexcept

Number of registered names.

Here is the caller graph for this function:

try_add()

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

inline

Non-throwing add.

Parameters

name	Object name (stored as-is; matched case-insensitively).

Returns

Assigned index, or -1 if name (in any case spelling) is already registered.

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 the index (case-insensitive), returning std::optional.

---

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

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