indigo. tools.hash

void setValue( T  val )

Sets the value pointed to by the iterator to val.  The iterator has to point to a valid item in a hash.

int gotoNextEqualKey()

Moves the iterator forward in the hash, as long as the key of the next item is identical to the current key, and returns true.  Otherwise it returns false, and the iterator is not changed.  This function should be used instead of opAddAssign() if you want to traverse all items with a specific key:

Hash!(int, char[]) hash;
hash.Iterator iter;

if ((iter = hash.find(25)) != hash.end)
{
  do
  {
    // do something with iter.
  }
  while (iter.gotoNextEqualKey);
}

Iterator find( Key  key )

Returns an iterator pointing to the item with key key in the hash, or end if the hash does not contain such a key.  If the hash contains more than one item with key key, this function an iterator pointing to the most recently inserted one.  The other values are accessible by incrementing the iterator.

See also value(Key).

int contains( Key  key )

Returns true if the hash contains key, otherwise false.

See also count().

size_t count( Key  key )

Returns the number of occurences of key in the hash.

See also contains().

T* ptrAt( Key  key )

Returns a pointer to the value associated with key key.  The hash must contain this key.  If there are multiple values for key in the hash, the function returns a pointer the most recently inserted one.  This function must be used if you want to call member functions of the value that change it.

See also value(Key).

alias ptrAt valuePtr

Returns a pointer to the value associated with a key.  This is an alias for ptrAt().

T value( Key  key )

Returns the value associated with key key, or a default constructed value if the hash does not contain such a key.  If there are multiple values for key in the hash, the function returns the most recently inserted one.

Note that you cannot use this function to call a member function of the value that needs to change the value.  This also applies to setting the length of a dynamic array.

See also find(), ptrAt().

T value( Key  key, T  defaultValue )

Returns the value associated with key key, or defaultValue if the hash does not contain such a key.  Overloaded function ─ see above for other details.

T[] values()

Returns an array containing all values in the hash, in ascending order of their keys.  If multiple values are associated with a key, all of them will be in the array.

See also value(Key), keys().

T[] values( Key  key )

Returns an array with all values associated to key key, from the most recently inserted to the least inserted one.  Overloaded function ─ see above for other details.

Key[] keys()

Returns an array containing all keys in the hash in arbitrary order.  Keys that occur multiple times in the hash occur multiple times in the array, too.  values() is ordered exactly the same way.

void reserve( size_t  size )

Preallocates enough memory for size elements.  This does not change the length of the hash.  But if you know in advance how many elements you need, you will get better performance if the hash has to be resized often.  Ideally size should be a bit larger than the actual number of elements you want to store.

See also capacity.

void clear()

Removes all elements from the hash.  Note that the internal storage is not freed with this operation, therefore the hash can still occupy a lot of memory.  Use free() to release it as well.

void squeeze()

Releases unused internal storage to the garbage collector.  This will not affect the nodes in the hash.  Call this function after deleting a lot of nodes, and only if you are sure you will not insert new nodes again.  Otherwise you will definitely fragment the memory.  The hash may still occupy a lot of unused memory after calling this function, especially if you inserted and deleted a lot of elements before.

See also free().

void free()

Removes all elements from the hash and makes the internal storage reavailable to the garbage collector.  Note that this storage will only be available again after a garbage collection, and if the hash contains objects their destructors will not be called until the collection.  To immediately delete the objects, use deleteAll() before free().

See also squeeze().

Iterator insert( Key  key, T  value )

Inserts a new item with the key key and the value value.  If there already is an item with key key, its value is replaced by value.  If there are multiple items with key key, the most recently inserted item is altered.

See also insertMulti().

Iterator insertMulti( Key  key, T  value )

Inserts a new item with the key key and the value value, even if there already is an item with the same key.

See also insert().

size_t remove( Key  key )

Removes all items from the hash that have the key key.  Returns the number of removed items.

See also take().

alias remove erase

Removes items from the hash.  Alias for remove().

T take( Key  key )

Removes the item with the key key from the hash and returns the value associated with it.  It the item does not exist in the hash, the function returns a default constructed value.  If there are multiple items with key key, only the most recently inserted one is removed.

See also remove().

void writeTo( DataStream  st )

Serializes this hash and all its items into the DataStream st.  This function is only available if the used types support serialization with DataStream, either because they are D builtin types, or because they provide writeTo() and readFrom() or createFrom() functions themselves.  Refer to the DataStream documentation for details.

void readFrom( DataStream  st )

Reads the contents of the hash previously serialized with writeTo() from the DataStream st.  This function is only available if the used types support serialization with DataStream, either because they are D builtin types, or because they provide writeTo() and readFrom() or createFrom() functions themselves.  Refer to the DataStream documentation for details.