Sitemap

 

Description

The Map Class

This class implements hash tables.

Throughout the documentation, the following prefixes will be used:

Global_

The library prefix: for applications, this is typically empty, for an xyz-Library, this is either XYZ_, xyz_ or Xyz, depending on the identifier in occurs in.

	Template		Instantiation
	Global_MAP_OK		XYZ_MAP_OK
	Global_map_new		xyz_map_new

Map_

This is equivalent to Global_map_iType_oType, or the name that was set with -name=... for this data structure. The case and underbar convention is adjusted, too.

Assuming a library prefix xyz and iType=int *, oType == int, you get:

	Template		Instantiation
	Map_t		xyz_map_int_p_int_t
	Map_ALLOW_NULL		XYZ_MAP_INT_P_INT_ALLOW_NULL

Map_class

This is the name of the data structure type in C++: capitalised and with underbars removed:

	Map_t		Map_class
	map_int_p_int_t		MapIntPInt

In the following, for many functions, the error code values are given. There are two kinds, those for success and those for failure. The error codes (if set at all) are always stored in the global variable Global_map_errno, no mattern whether the function returns its success or not. Note that the error value MAP_ERR_ASSERTIONFAILED is never explicitly given, because it

• can happen virtually always

• is considered a fatal error and should therefore lead to program abortion immediately.

Successful operation is indicated by Global_MAP_OK, Global_MAP_WARN_*, and Global_MAP_REHASH*.

Failure is indicated by Global_MAP_ERR_*. If a functions does not return the error code, its result value in case of an error is always the zero element of the result type. I.e. NULL for pointers, 0 for integers, the user specified zero element for iType or oType, Global_ERWIN_FALSE for Global_ERWIN_BOOL, etc.

Functions that only set map_errno to Global_MAP_REHASH_* or Global_MAP_OK will return void if they do not have a natural result.

Note

The term `success' means that the function could perform its operation according to the specification. E.g. if you call _insert and the key exists, the functions does not insert it. However, this is no error. It is defined that it should not be inserted in this case. Accordingly, you get a warning, not an error.

Type Aliases

Members

Detailed Descriptions

static void * operator new (size_t)

static void operator delete (void *, size_t)

static void * operator new[] (size_t)

static void operator delete[] (void *, size_t)

[constructor] Map ()

static Map_t const & static_zero ()

[constructor] Map (int initial_size)

[constructor] Map (oTypeTouched zero_element)

[constructor] Map (oTypeTouched zero_element, int initial_size)

int get_errno () const

void clear_errno () const

Resets the status code to MAP_OK.

If you do not have a thread-safe Erwin library, there is a macro with the same name as this function.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.

static int get_errno ()

static void clear_errno ()

[constructor] Map (Map_t const * a)

[constructor] Map (Map_t const & a)

Map_t * copy () const

Map_t * copy_err (int * err) const

Map_t & xchg (Map_t * other)

Exchanges the two maps' contents. No memory allocation is performed; this is a fast O(1) operation for swapping two values.

Map_t & xchg (Map_t & other)

Exchanges the two maps' contents. No memory allocation is performed; this is a fast O(1) operation for swapping two values.

Map_t & operator= (Map_t const &)

Map_t & operator= (Map_t const *)

without this, it would be copied twice

void _constructor ()

Quite private: do not use unless you know what you're doing:

This constructs the map for a given preallocated memory location.

FIXME: There should be an operator new() for this.

void _destructor ()

Quite private: do not use unless you know what you're doing:

Needed if you want to use maps without a pointer in vectors. vectors use C-style memory allocation because they need realloc. The constructor/destructors are invoked via these two functions.

[destructor] ~Map ()

There is no delete_flags here in C++, but you can clear_flags() before deletion.

operator Map_t * ()

operator Map_t const * () const

oTypeResult operator[] (iTypeParam i) const

Returns the found element or the zero element if not found.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_WARN_KEYNOTFOUND

Note that a warning means that the operation was successfully completed.

oType & operator[] (iTypeTouched i)

Returns a pointer to the found element or one to a newly allocated one. In the case when it was not possible to allocate space for a new element, the result NULL. Otherwise, it is not NULL.

If a new element was introduced, errno will be set to MAP_WARN_KEYNOTFOUND, otherwise to MAP_OK. Note again that in both cases, the result is non-NULL!

Note

If oType == oTypeVar, you may not use the pointer to directly write into the hash table because this circumvents copying and that is prohibited. Use poke_no_ocopy for things like that to make it explicit.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_WARN_KEYNOTFOUND

Note that a warning means that the operation was successfully completed.

oTypeIndex & operator[] (iTypeTouched i)

Returns the found element or introduces an empty element into the map and returns that (use Map_ENSURE_VALUE to determine the value that is introduced).

Also consider find_ptr_ensure if you want to modify the (newly introduced) value. Also see Map_ensure if you need the key, not the value after the operation.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_WARN_KEYNOTFOUND

Note that a warning means that the operation was successfully completed.

oType * find_ptr (iTypeParam i) const

Returns a pointer to the found element or NULL on failure.

Note

If oType == oTypeVar, you may not use the pointer to directly write into the hash table because this circumvents copying and that is prohibited. Use poke_no_ocopy for things like that to make it explicit.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_WARN_KEYNOTFOUND

Note that a warning means that the operation was successfully completed.

oType * find_ptr_ensure (iTypeTouched i)

Returns a pointer to the found element or one to a newly allocated one. In the case when it was not possible to allocate space for a new element, the result NULL. Otherwise, it is not NULL.

If a new element was introduced, errno will be set to MAP_WARN_KEYNOTFOUND, otherwise to MAP_OK. Note again that in both cases, the result is non-NULL!

Note

If oType == oTypeVar, you may not use the pointer to directly write into the hash table because this circumvents copying and that is prohibited. Use poke_no_ocopy for things like that to make it explicit.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_WARN_KEYNOTFOUND

Note that a warning means that the operation was successfully completed.

oType const * find_ptr (iTypeParam i) const

Returns a pointer to the found element or NULL on failure.

Note

If oType == oTypeVar, you may not use the pointer to directly write into the hash table because this circumvents copying and that is prohibited. Use poke_no_ocopy for things like that to make it explicit.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_WARN_KEYNOTFOUND

Note that a warning means that the operation was successfully completed.

oType const * find_ptr_ensure (iTypeTouched i)

Returns a pointer to the found element or one to a newly allocated one. In the case when it was not possible to allocate space for a new element, the result NULL. Otherwise, it is not NULL.

If a new element was introduced, errno will be set to MAP_WARN_KEYNOTFOUND, otherwise to MAP_OK. Note again that in both cases, the result is non-NULL!

Note

If oType == oTypeVar, you may not use the pointer to directly write into the hash table because this circumvents copying and that is prohibited. Use poke_no_ocopy for things like that to make it explicit.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_WARN_KEYNOTFOUND

Note that a warning means that the operation was successfully completed.

oTypeResult find (iTypeParam i) const

All other members map to the C equivalent directly.

Returns the found element or the zero element if not found.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_WARN_KEYNOTFOUND

Note that a warning means that the operation was successfully completed.

oTypeResult find_ensure (iTypeTouched i)

Returns the found element or introduces an empty element into the map and returns that (use Map_ENSURE_VALUE to determine the value that is introduced).

Also consider find_ptr_ensure if you want to modify the (newly introduced) value. Also see Map_ensure if you need the key, not the value after the operation.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_WARN_KEYNOTFOUND

Note that a warning means that the operation was successfully completed.

iTypeResult find_any_key () const

Returns some key that is stored in the table.

See Map_find_any() for docu.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_WARN_KEYNOTFOUND

Note that a warning means that the operation was successfully completed.

oTypeResult find_any () const

Returns the found element or the zero element if not found.

For maps with 0 or 1 elements and in the non-deterministic case, this is very fast. In the deterministic mode, this is O(n). In weak determinism, it is typically O(1) as in the non-deterministic mode. (The very unlikely worst case is always O(n)).

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_WARN_KEYNOTFOUND

Note that a warning means that the operation was successfully completed.

Map_element_ptr_t find_any_ptr () const

Returns a pointer to some element or NULL on failure.

Note

If oType == oTypeVar, you may not use the pointer to directly write into the hash table because this circumvents copying and that is prohibited. Use poke_no_ocopy for things like that to make it explicit.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_WARN_KEYNOTFOUND

Note that a warning means that the operation was successfully completed.

int find_any_pair (Map_key_result_t & kp, Map_element_ptr_t & vp) const

Map_t & insert (iTypeTouched k)

Map_t & insert (iTypeTouched k, oTypeTouched v)

Map_t & insert_map (Map_t const & other)

Inserts all keys from other into self. If any key is not inserted, returns WARN_EXISTINGKEY.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_WARN_EXISTINGKEY
• Global_MAP_REHASH_*
• If memory is exhausted, Global_MAP_ERR_NOMEM is signalled. If the option Map_NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

Note that a warning means that the operation was successfully completed.

Note that a rehash warning means that the operation was successfully completed. However, there may be serious problems like heap corruption, so handling this as an error is not a bad idea.

Map_t & insert_map (Map_t const * other)

Inserts all keys from other into self. If any key is not inserted, returns WARN_EXISTINGKEY.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_WARN_EXISTINGKEY
• Global_MAP_REHASH_*
• If memory is exhausted, Global_MAP_ERR_NOMEM is signalled. If the option Map_NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

Note that a warning means that the operation was successfully completed.

Note that a rehash warning means that the operation was successfully completed. However, there may be serious problems like heap corruption, so handling this as an error is not a bad idea.

Map_t & insert (Map_t const & other)

Inserts all keys from other into self. If any key is not inserted, returns WARN_EXISTINGKEY.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_WARN_EXISTINGKEY
• Global_MAP_REHASH_*
• If memory is exhausted, Global_MAP_ERR_NOMEM is signalled. If the option Map_NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

Note that a warning means that the operation was successfully completed.

Note that a rehash warning means that the operation was successfully completed. However, there may be serious problems like heap corruption, so handling this as an error is not a bad idea.

Map_t & insert (Map_t const * other)

Inserts all keys from other into self. If any key is not inserted, returns WARN_EXISTINGKEY.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_WARN_EXISTINGKEY
• Global_MAP_REHASH_*
• If memory is exhausted, Global_MAP_ERR_NOMEM is signalled. If the option Map_NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

Note that a warning means that the operation was successfully completed.

Note that a rehash warning means that the operation was successfully completed. However, there may be serious problems like heap corruption, so handling this as an error is not a bad idea.

oTypeVar modify (iTypeParam i, oTypeTouched v)

modify

Change an existing value for the given index (errno=OK). If the index does not exist, do not modify the map nothing (errno=WARN_KETNOTFOUND).

Returns the old value or Global_oType_ZERO if it is new in which case the map is not changed. Nothing is freed, value is copied.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_WARN_KEYNOTFOUND
• Global_MAP_REHASH_*
• If memory is exhausted, Global_MAP_ERR_NOMEM is signalled. If the option Map_NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

Note that a warning means that the operation was successfully completed.

Note that a rehash warning means that the operation was successfully completed. However, there may be serious problems like heap corruption, so handling this as an error is not a bad idea.

Map_t & modify_map (Map_t const & other)

like Map_modify on all entries in other. If any key was not found, WARN_KEYNOTFOUND is returned.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_WARN_KEYNOTFOUND
• Global_MAP_REHASH_*
• If memory is exhausted, Global_MAP_ERR_NOMEM is signalled. If the option Map_NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

Note that a warning means that the operation was successfully completed.

Note that a rehash warning means that the operation was successfully completed. However, there may be serious problems like heap corruption, so handling this as an error is not a bad idea.

Map_t & modify_map (Map_t const * other)

like Map_modify on all entries in other. If any key was not found, WARN_KEYNOTFOUND is returned.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_WARN_KEYNOTFOUND
• Global_MAP_REHASH_*
• If memory is exhausted, Global_MAP_ERR_NOMEM is signalled. If the option Map_NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

Note that a warning means that the operation was successfully completed.

Note that a rehash warning means that the operation was successfully completed. However, there may be serious problems like heap corruption, so handling this as an error is not a bad idea.

Map_t & modify (Map_t const & other)

like Map_modify on all entries in other. If any key was not found, WARN_KEYNOTFOUND is returned.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_WARN_KEYNOTFOUND
• Global_MAP_REHASH_*
• If memory is exhausted, Global_MAP_ERR_NOMEM is signalled. If the option Map_NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

Note that a warning means that the operation was successfully completed.

Note that a rehash warning means that the operation was successfully completed. However, there may be serious problems like heap corruption, so handling this as an error is not a bad idea.

Map_t & modify (Map_t const * other)

like Map_modify on all entries in other. If any key was not found, WARN_KEYNOTFOUND is returned.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_WARN_KEYNOTFOUND
• Global_MAP_REHASH_*
• If memory is exhausted, Global_MAP_ERR_NOMEM is signalled. If the option Map_NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

Note that a warning means that the operation was successfully completed.

Note that a rehash warning means that the operation was successfully completed. However, there may be serious problems like heap corruption, so handling this as an error is not a bad idea.

Map_t & set (iTypeTouched i, oTypeTouched v)

Insert or modify a value: introduce value for given index if it does not exist (errno=OK) or change value if index does exist (errno=WARN_EXISTINGKEY).

Similar to Map_modify, but value is freed and the status instead of the value is returned. Furthermore, of course, it is different in that if the value does not exist, it will be inserted.

Note

If you don't care whether to use Map_set or Map_insert, use Map_insert. Map_insert might be a little faster.

Result: The error code, same as Global_map_errno.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_WARN_EXISTINGKEY
• Global_MAP_REHASH_*
• If memory is exhausted, Global_MAP_ERR_NOMEM is signalled. If the option Map_NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

Note that a warning means that the operation was successfully completed.

Note that a rehash warning means that the operation was successfully completed. However, there may be serious problems like heap corruption, so handling this as an error is not a bad idea.

Map_t & set_map (Map_t const & other)

like Map_set on all entries in other

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_REHASH_*
• If memory is exhausted, Global_MAP_ERR_NOMEM is signalled. If the option Map_NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

Note that a rehash warning means that the operation was successfully completed. However, there may be serious problems like heap corruption, so handling this as an error is not a bad idea.

Map_t & set_map (Map_t const * other)

like Map_set on all entries in other

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_REHASH_*
• If memory is exhausted, Global_MAP_ERR_NOMEM is signalled. If the option Map_NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

Note that a rehash warning means that the operation was successfully completed. However, there may be serious problems like heap corruption, so handling this as an error is not a bad idea.

Map_t & set (Map_t const & other)

like Map_set on all entries in other

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_REHASH_*
• If memory is exhausted, Global_MAP_ERR_NOMEM is signalled. If the option Map_NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

Note that a rehash warning means that the operation was successfully completed. However, there may be serious problems like heap corruption, so handling this as an error is not a bad idea.

Map_t & set (Map_t const * other)

like Map_set on all entries in other

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_REHASH_*
• If memory is exhausted, Global_MAP_ERR_NOMEM is signalled. If the option Map_NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

Note that a rehash warning means that the operation was successfully completed. However, there may be serious problems like heap corruption, so handling this as an error is not a bad idea.

oTypeVar remove (iTypeTouched i)

remove

Returns the old value or Global_oType_ZERO. Does not free the value (which is returned), but only the key. A more appropriate name for this function might be `steal', because the value is kept.

In error-free operation, returns errno=OK if the index was found and erased, and WARN_KEYNOTFOUND if the index was not found.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_WARN_KEYNOTFOUND
• Global_MAP_REHASH_*

Note that a warning means that the operation was successfully completed.

Note that a rehash warning means that the operation was successfully completed. However, there may be serious problems like heap corruption, so handling this as an error is not a bad idea.

Map_t & remove_map (Map_t const & other)

like Map_remove on all entries in other. If any key was not found, WARN_KEYNOTFOUND is returned.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_WARN_KEYNOTFOUND
• Global_MAP_REHASH_*

Note that a warning means that the operation was successfully completed.

Note that a rehash warning means that the operation was successfully completed. However, there may be serious problems like heap corruption, so handling this as an error is not a bad idea.

Map_t & remove_map (Map_t const * other)

like Map_remove on all entries in other. If any key was not found, WARN_KEYNOTFOUND is returned.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_WARN_KEYNOTFOUND
• Global_MAP_REHASH_*

Note that a warning means that the operation was successfully completed.

Note that a rehash warning means that the operation was successfully completed. However, there may be serious problems like heap corruption, so handling this as an error is not a bad idea.

int remove_if (Map_feature_t f, bool value = true)

Remove some entries from the map according to a given feature. This is much faster than repeated deletions and maximally requires one rehash operation only.

Note

Even if the library is compiled with determinism, the order of the invocations of the feature callback is non-deterministic!

\errno (OK, REHASH_*)

Map_t & erase (iTypeTouched i)

erase

Same as Map_remove, but value is freed. In error-free operation, returns errno=OK if the index was found and erased, and WARN_KEYNOTFOUND if the index was not found.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_WARN_KEYNOTFOUND
• Global_MAP_REHASH_*

Note that a warning means that the operation was successfully completed.

Note that a rehash warning means that the operation was successfully completed. However, there may be serious problems like heap corruption, so handling this as an error is not a bad idea.

Map_t & erase_map (Map_t const & other)

like Map_erase on all entries in other. If any key was not found, WARN_KEYNOTFOUND is returned.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_WARN_KEYNOTFOUND
• Global_MAP_REHASH_*

Note that a warning means that the operation was successfully completed.

Note that a rehash warning means that the operation was successfully completed. However, there may be serious problems like heap corruption, so handling this as an error is not a bad idea.

Map_t & erase_map (Map_t const * other)

like Map_erase on all entries in other. If any key was not found, WARN_KEYNOTFOUND is returned.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_WARN_KEYNOTFOUND
• Global_MAP_REHASH_*

Note that a warning means that the operation was successfully completed.

Note that a rehash warning means that the operation was successfully completed. However, there may be serious problems like heap corruption, so handling this as an error is not a bad idea.

Map_t & erase (Map_t const & other)

like Map_erase on all entries in other. If any key was not found, WARN_KEYNOTFOUND is returned.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_WARN_KEYNOTFOUND
• Global_MAP_REHASH_*

Note that a warning means that the operation was successfully completed.

Note that a rehash warning means that the operation was successfully completed. However, there may be serious problems like heap corruption, so handling this as an error is not a bad idea.

Map_t & erase (Map_t const * other)

like Map_erase on all entries in other. If any key was not found, WARN_KEYNOTFOUND is returned.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_WARN_KEYNOTFOUND
• Global_MAP_REHASH_*

Note that a warning means that the operation was successfully completed.

Note that a rehash warning means that the operation was successfully completed. However, there may be serious problems like heap corruption, so handling this as an error is not a bad idea.

int erase_if (Map_feature_t f, bool value = true)

Erase some entries from the map according to a given feature. This is much faster than repeated deletions and maximally requires one rehash operation only.

Note

Even if the library is compiled with determinism, the order of the invocations of the feature callback is non-deterministic!

\errno (OK, REHASH_*)

Map_t & intersect (Map_t const & other)

Implements set intersection: this invokes Map_erase on all entries in self that are not in other. Returns the number of erased elements (quite like Map_erase_if).

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_REHASH_*
• If memory is exhausted, Global_MAP_ERR_NOMEM is signalled. If the option Map_NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

Note that a rehash warning means that the operation was successfully completed. However, there may be serious problems like heap corruption, so handling this as an error is not a bad idea.

Map_t & intersect (Map_t const * other)

Implements set intersection: this invokes Map_erase on all entries in self that are not in other. Returns the number of erased elements (quite like Map_erase_if).

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_REHASH_*
• If memory is exhausted, Global_MAP_ERR_NOMEM is signalled. If the option Map_NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

Note that a rehash warning means that the operation was successfully completed. However, there may be serious problems like heap corruption, so handling this as an error is not a bad idea.

Map_t & intersect_no_resize (Map_t const & other)

Like Map_intersect, but does not shrink the internal hash table.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_REHASH_*
• If memory is exhausted, Global_MAP_ERR_NOMEM is signalled. If the option Map_NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

Note that a rehash warning means that the operation was successfully completed. However, there may be serious problems like heap corruption, so handling this as an error is not a bad idea.

Map_t & intersect_no_resize (Map_t const * other)

Like Map_intersect, but does not shrink the internal hash table.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_REHASH_*
• If memory is exhausted, Global_MAP_ERR_NOMEM is signalled. If the option Map_NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

Note that a rehash warning means that the operation was successfully completed. However, there may be serious problems like heap corruption, so handling this as an error is not a bad idea.

iTypeResult find_key (iTypeParam i) const

others

Returns the key as stored in the table. For copied pointer types, this might be different from index.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_WARN_KEYNOTFOUND

Note that a warning means that the operation was successfully completed.

oTypeResult zero () const

Returns the zero element of oType

Error Codes

The operation is always successful (not thinking of assertion failures).

iTypeResult ensure (iTypeTouched k)

This ensures that key is inserted in the table, i.e., it allocates a cell for it. The inserted value will be Global_oType_ZERO. If you want to change this, re-define Map_ENSURE_VALUE. The result is the key as inserted in the hash table, so if you defined Global_iType_ICOPY, you will get a copy of your key.

Note

This function implements symbol tables.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_WARN_EXISTINGKEY
• Global_MAP_REHASH_*
• If memory is exhausted, Global_MAP_ERR_NOMEM is signalled. If the option Map_NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

Note that a warning means that the operation was successfully completed.

Note that a rehash warning means that the operation was successfully completed. However, there may be serious problems like heap corruption, so handling this as an error is not a bad idea.

iTypeResult ensure_no_icopy (iTypeVarParam k)

This is like Map_ensure(), but the input key will be stolen or freed, i.e., it will be used as a copy inside the hash table, instead of being copied as in Map_ensure. If the key already exists, the key passed will be freed.

Note

This function implements symbol tables.

This could be called Map_ensure_steal(), but we already have poke_no_icopy().

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_WARN_EXISTINGKEY
• Global_MAP_REHASH_*
• If memory is exhausted, Global_MAP_ERR_NOMEM is signalled. If the option Map_NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

Note that a warning means that the operation was successfully completed.

Note that a rehash warning means that the operation was successfully completed. However, there may be serious problems like heap corruption, so handling this as an error is not a bad idea.

iTypeResult operator() (iTypeTouched k)

This ensures that key is inserted in the table, i.e., it allocates a cell for it. The inserted value will be Global_oType_ZERO. If you want to change this, re-define Map_ENSURE_VALUE. The result is the key as inserted in the hash table, so if you defined Global_iType_ICOPY, you will get a copy of your key.

Note

This function implements symbol tables.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_WARN_EXISTINGKEY
• Global_MAP_REHASH_*
• If memory is exhausted, Global_MAP_ERR_NOMEM is signalled. If the option Map_NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

Note that a warning means that the operation was successfully completed.

Note that a rehash warning means that the operation was successfully completed. However, there may be serious problems like heap corruption, so handling this as an error is not a bad idea.

Map_t & poke (iType * kp, iTypeTouched k, bool aintroduce = true)

Map_t & poke (iType * kp, oTypeVar * vo, iTypeTouched k, oTypeTouched v, bool aintroduce = true, bool aoverwrite = true)

Map_t & poke_no_icopy (iType * kp, iTypeVarParam k, bool aintroduce = true)

Map_t & poke_no_icopy (iType * kp, oTypeVar * vo, iTypeVarParam k, oTypeTouched v, bool aintroduce = true, bool aoverwrite = true)

Map_t & poke_no_ocopy (iType * kp, oTypeVar * vo, iTypeTouched k, oTypeVarParam v, bool aintroduce = true, bool aoverwrite = true)

Like Map_poke, but the value is not copied. However, value may be freed if value_out is NULL. The rules for copying and freeing values are the same as for key with Map_poke_no_icopy.

Map_t & poke_no_icopy_no_ocopy (iType * kp, oTypeVar * vo, iTypeVarParam k, oTypeVarParam v, bool aintroduce = true, bool aoverwrite = true)

Like Map_poke, but neither the key nor the value are copied. Both, key and value may be freed. The rules for copying and freeing keys and values are the same as for Map_poke_no_icopy and Map_poke_no_ocopy.

Map_t & clear ()

clear

Like Map_erase for all elements

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.

Map_t & clear_no_resize ()

Like Map_erase for all elements, but does not shrink the internal hash table.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.

Map_t & clear (bool k, bool v)

Clear and selectively free the map

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.

int nentries () const

Returns the number of entries (pairs of keys and values)

Error Codes

The operation is always successful (not thinking of assertion failures).

bool empty () const

Returns whether map has 0 entries

Error Codes

The operation is always successful (not thinking of assertion failures).

bool non_empty () const

Returns whether map has 0 entries

Error Codes

The operation is always successful (not thinking of assertion failures).

iType * get_keys () const

Get all keys, values, or key/value pairs as a normal standard C array. The elements and keys are not copied. The array will be terminated with the zero value.

Note

The returned maps are newly allocated and must eventually be freed by the user using Map_delete_keys(). In earlier versions of Erwin, free() was recommended for freeing, but due to more sophisticated memory management, Map_delete_keys() is the primary choice now. It old code, no adjustment should be necessary, since this is only different if you customise Global_ERWIN_TMALLOC etc.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• If memory is exhausted, Global_MAP_ERR_NOMEM is signalled. If the option Map_NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

static void delete_keys (iType * k)

Deallocate keys obtained by Map_get_keys().

Map_pair_t * get_entries () const

Use Map_delete_entries to deallocate the returned array.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• If memory is exhausted, Global_MAP_ERR_NOMEM is signalled. If the option Map_NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

Map_pair_ptr_t * get_entries_ptr () const

Usp Map_delete_entries_ptr to deallocate the returned array.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• If memory is exhausted, Global_MAP_ERR_NOMEM is signalled. If the option Map_NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

oType * get_values () const

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• If memory is exhausted, Global_MAP_ERR_NOMEM is signalled. If the option Map_NOMEM_IS_FATAL is 1, this error cannot happen: instead, the program is immediately terminated.

static void delete_entries_ptr (Map_pair_ptr_t * k)

Deallocate keys obtained by Map_get_entries_ptr().

static void delete_entries (Map_pair_t * k)

Deallocate keys obtained by Map_get_entries().

static void delete_values (oType * k)

Deallocate keys obtained by Map_get_values().

int hash_size () const

Returns the size of the internal array of list pointers used to implement the hash table.

Error Codes

The operation is always successful (not thinking of assertion failures).

Map_t & rehash (int n)

Do a manual rehash. If Global_map_errno holds anything other than MAP_OK, the map operation did not succeed. However, the map is guaranteed to be usable after the function call; either rehashed or original. The return type is set to void because the function should not be considered failed if anything bad has happened.

Error Codes (Global_map_errno)

• In case of operation, Global_MAP_OK is signalled.
• Global_MAP_REHASH_*

Note that a rehash warning means that the operation was successfully completed. However, there may be serious problems like heap corruption, so handling this as an error is not a bad idea.

double average_line_length () const

double variance_line_length () const

double deviation_line_length () const

int max_line_length () const

int min_line_length () const

void dump (FILE * f) const

Dumps the internal structure of the map to the given file.

int nrehash_ops () const