#include <evo/map.h>

Inheritance diagram for Map< TKey, TValue, TSize >:

Detailed Description

template<class TKey, class TValue, class TSize = SizeT>
class evo::Map< TKey, TValue, TSize >

Associative container holding key/value pairs for fast lookup.

Template Parameters

TKey	Map key type
TValue	Map value type
TSize	Size type to use for size values (must be unsigned integer) – default: SizeT

Features

Interface similar to STL map
Keys are always unique (no duplicates)
Implementations:
- MapList (ordered)
- MapHash (unordered)
For best performance use concrete map types instead of the general interface (Map)

Iterators

Map::Iter – Read-Only Iterator (IteratorBi)
Map::IterM – Mutable Iterator (IteratorBi)

Caution: Modifying or resizing a map will shift or invalidate existing iterators using it.

Read Access

asconst()
size()
- null(), empty()
- capacity()
- shared()
- ordered()
contains(const Key&) const
cbegin(), cend()
- begin() const, end() const
find()
- iter()
operator==()
- operator!=()

Modifiers

Helpers

Comparison Object

Maps that use a hash/comparison type will have these additional methods (not included in this interface), where T is the hash/compare type used:

const T& get_compare() const
T& get_compare()

See MapList or MapHash for example.

Ordered Maps

Ordered maps will have these additional methods (not included in this interface):

Iter iter_lower(const Key& value) const
Iter iter_upper(const Key& value) const
IterM iter_lowerM(const Key& value)
IterM iter_upperM(const Key& value)
Size remove(const Value& Key, Size count)
Size remove_range(IterM& Key, Size count)
Size remove_range(IterM& Key, IterM& end)

See MapList for example.

List Maps

List maps will have these additional methods (not included in this interface):

Size item(Size index) const
Size removeat(Size index)

See MapList for example.

Example

See implementation types for examples: MapList, MapHash

Classes
struct	InitPair
	Initializer key/value pair, used with initializer (C++11). More...

Public Types
typedef void	EvoContainerType

typedef Pair< Key, Value >	Item
	Item type (key/value pair) More...

typedef IteratorBi< ThisType >::Const	Iter
	Iterator (const) - IteratorBi. More...

typedef IteratorBi< ThisType >	IterM
	Iterator (mutable) - IteratorBi. More...

typedef TKey	Key
	Key type. More...

using	KeyPass = typename DataCopy< TKey >::PassType
	Key type for passing through InitPair (C++11) More...

typedef Map< TKey, TValue, TSize >	MapBaseType
	Map base type More...

typedef TSize	Size
	Size type for size values (must be unsigned integer) – default: SizeT. More...

typedef Map< TKey, TValue, TSize >	ThisType
	This type. More...

typedef TValue	Value
	Value type. More...

using	ValuePass = typename DataCopy< TValue >::PassType
	Value type for passing through InitPair (C++11) More...

Public Member Functions
virtual	~Map ()
	Destructor. More...

virtual Item &	add (const Key &key, const Value &value, bool update=true)=0
	Add or update using given key and value. More...

virtual Item &	add (const Item &item, bool update=true)=0
	Add or update using given item. More...

virtual MapBaseType &	add (const MapBaseType &map, bool update=true)=0
	Add items from given map. More...

template<class T >
Size	addsplit (const T &str, char delim=',', char kvdelim='=')
	Split delimited string into map key/value items. More...

const MapBaseType &	asconst () const
	Explicitly use a const reference to this. More...

IterM	begin ()
	Get iterator at first item (mutable). More...

Iter	begin () const
	Get iterator at first item (const). More...

virtual Size	capacity () const =0
	Get map capacity. More...

virtual MapBaseType &	capacity (Size size)=0
	Set map capacity. More...

virtual MapBaseType &	capacitymin (Size min)=0
	Set map capacity to at least given minimum. More...

Iter	cbegin () const
	Get iterator at first item (const). More...

Iter	cend () const
	Get iterator at end (const). More...

virtual MapBaseType &	clear ()=0
	Clear by removing all items. More...

virtual MapBaseType &	compact ()
	Reduce capacity to fit current size (modifier). More...

virtual bool	contains (const Key &key) const =0
	Get whether map contains the given key. More...

bool	empty () const
	Get whether map is empty (size is 0). More...

IterM	end ()
	Get iterator at end. More...

Iter	end () const
	Get iterator at end (const). More...

virtual const Value *	find (const Key &key) const =0
	Find (lookup) value for given key (const). More...

virtual Value *	findM (const Key &key)=0
	Find (lookup) value for given key (mutable). More...

Value &	get (const Key &key, bool *created=NULL)
	Get item value for key (mutable). More...

virtual Item &	getitem (const Key &key, bool *created=NULL)=0
	Get map item for key (mutable). More...

Iter	iter (const Key &key) const
	Find (lookup) iterator for given key (const). More...

IterM	iterM (const Key &key)
	Find (lookup) iterator for given key (mutable). More...

virtual bool	null () const =0
	Get whether map is null. More...

bool	operator!= (const MapBaseType &map) const
	Inequality operator. More...

MapBaseType &	operator= (const MapBaseType &src)
	Assignment operator. More...

bool	operator== (const MapBaseType &map) const
	Equality operator. More...

Value &	operator[] (const Key &key)
	Get item value for key (mutable). More...

bool	ordered () const
	Get whether map is ordered. More...

virtual bool	remove (const Key &key)=0
	Find and remove item with given key. More...

virtual bool	remove (IterM &iter, IteratorDir dir=iterNONE)=0
	Remove item using given iterator. More...

MapBaseType &	reserve (Size size)
	Reserve space for new items. More...

virtual MapBaseType &	set ()=0
	Set as null and empty. More...

virtual MapBaseType &	set (const MapBaseType &src)=0
	Set as copy of given map. More...

virtual MapBaseType &	setempty ()=0
	Set as empty but not null. More...

virtual bool	shared () const =0
	Get whether shared. More...

Size	size () const
	Get map size (number of items). More...

virtual MapBaseType &	unshare ()=0
	Make data unique by allocating new buffer, if needed (modifier). More...

Protected Member Functions
	Map ()
	Constructor. More...

	Map (bool ordered)
	Constructor. More...

	Map (const Map &)=delete
	Copy constructor (disabled). More...

virtual const Item *	getiter (IterKey &iterkey, const Key &key) const =0
	Used by base class to get data to initialize iterator. More...

Protected Attributes
bool	ordered_
	Whether map is ordered (items are kept in order by key) More...

Size	size_
	Map size (number of items, automatically updated by concrete set members) More...

Member Typedef Documentation

◆ EvoContainerType

typedef void EvoContainerType

◆ Item

typedef Pair<Key,Value> Item

Item type (key/value pair)

◆ Iter

typedef IteratorBi<ThisType>::Const Iter

Iterator (const) - IteratorBi.

◆ IterM

typedef IteratorBi<ThisType> IterM

Iterator (mutable) - IteratorBi.

◆ Key

typedef TKey Key

Key type.

◆ KeyPass

using KeyPass = typename DataCopy<TKey>::PassType

Key type for passing through InitPair (C++11)

◆ MapBaseType

typedef Map<TKey,TValue,TSize> MapBaseType

Map base type

◆ Size

typedef TSize Size

Size type for size values (must be unsigned integer) – default: SizeT.

◆ ThisType

typedef Map<TKey,TValue,TSize> ThisType

This type.

◆ Value

typedef TValue Value

Value type.

◆ ValuePass

using ValuePass = typename DataCopy<TValue>::PassType

Value type for passing through InitPair (C++11)

Constructor & Destructor Documentation

◆ Map() [1/3]

Map ( )

inlineprotected

Constructor.

Used by derived types.

◆ Map() [2/3]

Map ( bool ordered )

inlineprotected

Constructor.

Used by derived types.

Parameters

ordered Whether map is ordered

◆ Map() [3/3]

Map ( const Map< TKey, TValue, TSize > & )

protecteddelete

Copy constructor (disabled).

◆ ~Map()

virtual ~Map ( )

inlinevirtual

Destructor.

Member Function Documentation

◆ add() [1/3]

virtual Item& add	(	const Key &	key,
		const Value &	value,
		bool	update = `true`
	)

pure virtual

Add or update using given key and value.

Parameters

key	Key to find/add (copied)
value	Value to add/update (copied)
update	Whether to update value for existing item

Returns: Item added/updated

Implemented in MapHash< TKey, TValue, THash, TSize >, MapList< TKey, TValue, TCompare, TSize >, MapList< String, CommandInfo >, MapList< SigNumType, Handler >, and MapList< String, OptionInfoShPtr >.

◆ add() [2/3]

virtual Item& add	(	const Item &	item,
		bool	update = `true`
	)

pure virtual

Add or update using given item.

Parameters

item	Item to use for add/update (copied)
update	Whether to update value for existing item

Returns: Item added/updated

Implemented in MapHash< TKey, TValue, THash, TSize >, MapList< TKey, TValue, TCompare, TSize >, MapList< String, CommandInfo >, MapList< SigNumType, Handler >, and MapList< String, OptionInfoShPtr >.

◆ add() [3/3]

virtual MapBaseType& add	(	const MapBaseType &	map,
		bool	update = `true`
	)

pure virtual

Add items from given map.

Parameters

map	Map to add items from
update	Whether to update value for existing items

Returns: This

Implemented in MapList< TKey, TValue, TCompare, TSize >, MapList< String, CommandInfo >, MapList< SigNumType, Handler >, and MapList< String, OptionInfoShPtr >.

◆ addsplit()

Size addsplit	(	const T &	str,
		char	delim = `','`,
		char	kvdelim = `'='`
	)

inline

Split delimited string into map key/value items.

This parses/tokenizes str and adds each item to map, using convert() for conversion to map key and value types
Map key and value types must be convertible from String via convert()
See joinmap() to join map back into string

Template Parameters

T	String type to parse – inferred from str parameter

Parameters

str	String to parse
delim	Item delimiter to use
kvdelim	Key/Value delimiter to use

Returns: Number of items added to map

◆ asconst()

const MapBaseType& asconst ( ) const

inline

Explicitly use a const reference to this.

This is useful to force using this as const without casting

Returns: This

◆ begin() [1/2]

IterM begin ( )

inline

Get iterator at first item (mutable).

This allows compatibility with range-based for loops and other libraries, otherwise use container Iter directly
cbegin() is more efficient, since this effectively calls unshare() to make items mutable

Returns: Iterator at first item, or at end position if empty

See also: IterM, end(), cbegin(), cend()

◆ begin() [2/2]

Iter begin ( ) const

inline

Get iterator at first item (const).

This allows compatibility with range-based for loops and other libraries, otherwise use container Iter directly

Returns: Iterator at first item, or at end position if empty

See also: end() const, cbegin()

◆ capacity() [1/2]

virtual Size capacity ( ) const

pure virtual

Get map capacity.

Returns: Current capacity

Implemented in MapList< TKey, TValue, TCompare, TSize >, MapList< String, CommandInfo >, MapList< SigNumType, Handler >, MapList< String, OptionInfoShPtr >, and MapHash< TKey, TValue, THash, TSize >.

◆ capacity() [2/2]

virtual MapBaseType& capacity ( Size size )

pure virtual

Set map capacity.

This is just a suggestion – some implementations may ignore it

Parameters

size	New capacity

Returns: This

Implemented in MapHash< TKey, TValue, THash, TSize >, MapList< TKey, TValue, TCompare, TSize >, MapList< String, CommandInfo >, MapList< SigNumType, Handler >, and MapList< String, OptionInfoShPtr >.

◆ capacitymin()

virtual MapBaseType& capacitymin ( Size min )

pure virtual

Set map capacity to at least given minimum.

This is just a suggestion – some implementations may ignore it

Parameters

min	Minimum capacity

Returns: This

Implemented in MapHash< TKey, TValue, THash, TSize >, MapList< TKey, TValue, TCompare, TSize >, MapList< String, CommandInfo >, MapList< SigNumType, Handler >, and MapList< String, OptionInfoShPtr >.

◆ cbegin()

Iter cbegin ( ) const

inline

Get iterator at first item (const).

This allows compatibility with range-based for loops and other libraries, otherwise use container Iter directly

Returns: Iterator at first item, or at end position if empty

See also: Iter, cend(), begin(), end()

◆ cend()

Iter cend ( ) const

inline

Get iterator at end (const).

This allows compatibility with range-based for loops and other libraries, otherwise use container Iter directly
This really just creates an empty iterator

Returns: Iterator at end position

See also: Iter, cbegin(), begin(), end()

◆ clear()

virtual MapBaseType& clear ( )

pure virtual

Clear by removing all items.

Does not set as null – null status is unchanged

Returns: This

Implemented in MapList< TKey, TValue, TCompare, TSize >, MapList< String, CommandInfo >, MapList< SigNumType, Handler >, MapList< String, OptionInfoShPtr >, and MapHash< TKey, TValue, THash, TSize >.

◆ compact()

virtual MapBaseType& compact ( )

inlinevirtual

Reduce capacity to fit current size (modifier).

Call to save memory when done adding items
This is just a suggestion – some implementations may ignore it

Returns: This

Reimplemented in MapList< TKey, TValue, TCompare, TSize >, MapList< String, CommandInfo >, MapList< SigNumType, Handler >, and MapList< String, OptionInfoShPtr >.

◆ contains()

virtual bool contains ( const Key & key ) const

pure virtual

Get whether map contains the given key.

See also: map_contains()

Parameters

key	Key to look for

Returns: Whether key was found

Implemented in MapList< TKey, TValue, TCompare, TSize >, MapList< String, CommandInfo >, MapList< SigNumType, Handler >, MapList< String, OptionInfoShPtr >, and MapHash< TKey, TValue, THash, TSize >.

◆ empty()

bool empty ( ) const

inline

Get whether map is empty (size is 0).

Returns: Whether empty

◆ end() [1/2]

IterM end ( )

inline

Get iterator at end.

This allows compatibility with range-based for loops and other libraries, otherwise use container Iter directly
This really just creates an empty iterator

Returns: Iterator at end position

See also: IterM, begin(), cbegin(), cend()

◆ end() [2/2]

Iter end ( ) const

inline

Get iterator at end (const).

This allows compatibility with range-based for loops and other libraries, otherwise use container Iter directly
This really just creates an empty iterator

Returns: Iterator at end position

See also: begin() const, cend()

◆ find()

virtual const Value* find ( const Key & key ) const

pure virtual

Find (lookup) value for given key (const).

Parameters

key	Key to find

Returns: Found value const pointer, NULL if not found

Implemented in MapList< TKey, TValue, TCompare, TSize >, MapList< String, CommandInfo >, MapList< SigNumType, Handler >, MapList< String, OptionInfoShPtr >, and MapHash< TKey, TValue, THash, TSize >.

◆ findM()

virtual Value* findM ( const Key & key )

pure virtual

Find (lookup) value for given key (mutable).

Parameters

key	Key to find

Returns: Found value pointer, NULL if not found

Implemented in MapList< TKey, TValue, TCompare, TSize >, MapList< String, CommandInfo >, MapList< SigNumType, Handler >, MapList< String, OptionInfoShPtr >, and MapHash< TKey, TValue, THash, TSize >.

◆ get()

Value& get	(	const Key &	key,
		bool *	created = `NULL`
	)

inline

Get item value for key (mutable).

Item is created with default value if not found

Parameters

key	Key to use
created	Stores whether new item was created, if not NULL

Returns: Value reference for key

◆ getitem()

virtual Item& getitem	(	const Key &	key,
		bool *	created = `NULL`
	)

pure virtual

Get map item for key (mutable).

Item is created with default value if not found.

Parameters

key	Key to use
created	Stores whether new item was created, if not NULL

Returns: Value reference for key

Implemented in MapList< TKey, TValue, TCompare, TSize >, MapList< String, CommandInfo >, MapList< SigNumType, Handler >, MapList< String, OptionInfoShPtr >, and MapHash< TKey, TValue, THash, TSize >.

◆ getiter()

virtual const Item* getiter	(	IterKey &	iterkey,
		const Key &	key
	)		const

protectedpure virtual

Used by base class to get data to initialize iterator.

Parameters

iterkey	Set to iterator data, if item found
key	Key to find

Returns: Item pointer, NULL if not found

Implemented in MapHash< TKey, TValue, THash, TSize >, MapList< TKey, TValue, TCompare, TSize >, MapList< String, CommandInfo >, MapList< SigNumType, Handler >, and MapList< String, OptionInfoShPtr >.

◆ iter()

Iter iter ( const Key & key ) const

inline

Find (lookup) iterator for given key (const).

Parameters

key	Key to find

Returns: Iterator, at end position if not key not found

◆ iterM()

IterM iterM ( const Key & key )

inline

Find (lookup) iterator for given key (mutable).

Parameters

key	Key to find

Returns: Iterator, at end position if not key not found

◆ null()

virtual bool null ( ) const

pure virtual

Get whether map is null.

Returns: Whether null

Implemented in MapList< TKey, TValue, TCompare, TSize >, MapList< String, CommandInfo >, MapList< SigNumType, Handler >, MapList< String, OptionInfoShPtr >, and MapHash< TKey, TValue, THash, TSize >.

◆ operator!=()

bool operator!= ( const MapBaseType & map ) const

inline

Inequality operator.

Parameters

map	Map to compre

Returns: Whether maps are not equal (don't have same keys and values)

◆ operator=()

MapBaseType& operator= ( const MapBaseType & src )

inline

Assignment operator.

Parameters

src	Source to copy

Returns: This

◆ operator==()

bool operator== ( const MapBaseType & map ) const

inline

Equality operator.

Parameters

map	Map to compre

Returns: Whether maps are equal (have same keys and values)

◆ operator[]()

Value& operator[] ( const Key & key )

inline

Get item value for key (mutable).

Item is created with default value if not found
Same as get(const Key&)

Parameters

key	Key to use

Returns: Value reference for key

◆ ordered()

bool ordered ( ) const

inline

Get whether map is ordered.

Ordered maps keep items in order by key so iteration is predictable

◆ remove() [1/2]

virtual bool remove ( const Key & key )

pure virtual

Find and remove item with given key.

Caution: Removing an item may shift other iterators on same map, in an unpredictable way – see remove(IterM&,IteratorDir)

Parameters

key	Key to use

Returns: Whether key was removed, false if not found

Implemented in MapHash< TKey, TValue, THash, TSize >, MapList< TKey, TValue, TCompare, TSize >, MapList< String, CommandInfo >, MapList< SigNumType, Handler >, and MapList< String, OptionInfoShPtr >.

◆ remove() [2/2]

virtual bool remove	(	IterM &	iter,
		IteratorDir	dir = `iterNONE`
	)

pure virtual

Remove item using given iterator.

This will move the iterator to the next item according to dir, or end position if no more
Caution: Removing an item may shift other iterators on same map, in an unpredictable way

Parameters

iter	Iterator position
dir	Direction to move iterator to next item, iterNONE for end position

Returns: Whether item was removed, false if iterator at end position

Implemented in MapHash< TKey, TValue, THash, TSize >, MapHash< TKey, TValue, THash, TSize >, MapList< TKey, TValue, TCompare, TSize >, MapList< String, CommandInfo >, MapList< SigNumType, Handler >, MapList< String, OptionInfoShPtr >, MapList< TKey, TValue, TCompare, TSize >, MapList< String, CommandInfo >, MapList< SigNumType, Handler >, and MapList< String, OptionInfoShPtr >.

◆ reserve()

MapBaseType& reserve ( Size size )

inline

Reserve space for new items.

For best performance, call this before adding multiple items
This calls capacitymin() with current size + size to reserve space
This is just a suggestion – some implementations may ignore it

Parameters

size	Size to reserve

Returns: This

◆ set() [1/2]

virtual MapBaseType& set ( )

pure virtual

Set as null and empty.

Returns: This

Implemented in MapList< TKey, TValue, TCompare, TSize >, MapList< String, CommandInfo >, MapList< SigNumType, Handler >, MapList< String, OptionInfoShPtr >, and MapHash< TKey, TValue, THash, TSize >.

◆ set() [2/2]

virtual MapBaseType& set ( const MapBaseType & src )

pure virtual

Set as copy of given map.

This clears all items in current map.

Parameters

src	Source map

Returns: This

Implemented in MapList< TKey, TValue, TCompare, TSize >, MapList< String, CommandInfo >, MapList< SigNumType, Handler >, MapList< String, OptionInfoShPtr >, MapList< TKey, TValue, TCompare, TSize >, MapList< String, CommandInfo >, MapList< SigNumType, Handler >, MapList< String, OptionInfoShPtr >, and MapHash< TKey, TValue, THash, TSize >.

◆ setempty()

virtual MapBaseType& setempty ( )

pure virtual

Set as empty but not null.

Returns: This

Implemented in MapList< TKey, TValue, TCompare, TSize >, MapList< String, CommandInfo >, MapList< SigNumType, Handler >, MapList< String, OptionInfoShPtr >, and MapHash< TKey, TValue, THash, TSize >.

◆ shared()

virtual bool shared ( ) const

pure virtual

Get whether shared.

Data is shared when referencing external data or buffer is allocated and shared (reference count > 1)

Returns: Whether shared

Implemented in MapList< TKey, TValue, TCompare, TSize >, MapList< String, CommandInfo >, MapList< SigNumType, Handler >, MapList< String, OptionInfoShPtr >, and MapHash< TKey, TValue, THash, TSize >.

◆ size()

Size size ( ) const

inline

Get map size (number of items).

Returns: Map size

◆ unshare()

virtual MapBaseType& unshare ( )

pure virtual

Make data unique by allocating new buffer, if needed (modifier).

Use reserve() instead to reserve additional space while unsharing
Use to make buffer unique (not shared) and writable (when not empty)
This is called automatically by mutable/modifier methods
This does nothing if empty or not shared

Returns: This

Implemented in MapHash< TKey, TValue, THash, TSize >, MapList< TKey, TValue, TCompare, TSize >, MapList< String, CommandInfo >, MapList< SigNumType, Handler >, and MapList< String, OptionInfoShPtr >.

Member Data Documentation

◆ ordered_

bool ordered_

protected

Whether map is ordered (items are kept in order by key)

◆ size_

Size size_

protected

Map size (number of items, automatically updated by concrete set members)

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

evo/map.h

Detailed Description

template<class TKey, class TValue, class TSize = SizeT> class evo::Map< TKey, TValue, TSize >

Classes

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Member Typedef Documentation

◆ EvoContainerType

◆ Item

◆ Iter

◆ IterM

◆ Key

◆ KeyPass

◆ MapBaseType

◆ Size

◆ ThisType

◆ Value

◆ ValuePass

Constructor & Destructor Documentation

◆ Map() [1/3]

◆ Map() [2/3]

◆ Map() [3/3]

◆ ~Map()

Member Function Documentation

◆ add() [1/3]

◆ add() [2/3]

◆ add() [3/3]

◆ addsplit()

◆ asconst()

◆ begin() [1/2]

◆ begin() [2/2]

◆ capacity() [1/2]

◆ capacity() [2/2]

◆ capacitymin()

◆ cbegin()

◆ cend()

◆ clear()

◆ compact()

◆ contains()

◆ empty()

◆ end() [1/2]

◆ end() [2/2]

◆ find()

◆ findM()

◆ get()

◆ getitem()

◆ getiter()

◆ iter()

◆ iterM()

◆ null()

◆ operator!=()

◆ operator=()

◆ operator==()

◆ operator[]()

◆ ordered()

◆ remove() [1/2]

◆ remove() [2/2]

◆ reserve()

◆ set() [1/2]

◆ set() [2/2]

◆ setempty()

◆ shared()

◆ size()

◆ unshare()

Member Data Documentation

◆ ordered_

◆ size_

template<class TKey, class TValue, class TSize = SizeT>
class evo::Map< TKey, TValue, TSize >