Functions
LuaHashMapIterator	LuaHashMap_GetIteratorAtBegin (LuaHashMap *hash_map)
	Returns an iterator at the start position of the hash table.

LuaHashMapIterator	LuaHashMap_GetIteratorAtEnd (LuaHashMap *hash_map)
	Returns an iterator at the end position of the hash table.

bool	LuaHashMap_IteratorNext (LuaHashMapIterator *hash_iterator)
	Increments the iterator to the next item in the hash table.

LuaHashMapIterator	LuaHashMap_GetIteratorForKeyString (LuaHashMap restrict hash_map, const char restrict key_string)
	Returns an iterator corresponding to the specified key.

LuaHashMapIterator	LuaHashMap_GetIteratorForKeyStringWithLength (LuaHashMap restrict hash_map, const char restrict key_string, size_t key_string_length)
	Returns an iterator corresponding to the specified key.

LuaHashMapIterator	LuaHashMap_GetIteratorForKeyPointer (LuaHashMap hash_map, void key_pointer)
	Returns an iterator corresponding to the specified key.

LuaHashMapIterator	LuaHashMap_GetIteratorForKeyNumber (LuaHashMap *hash_map, lua_Number key_number)
	Returns an iterator corresponding to the specified key.

LuaHashMapIterator	LuaHashMap_GetIteratorForKeyInteger (LuaHashMap *hash_map, lua_Integer key_integer)
	Returns an iterator corresponding to the specified key.

bool	LuaHashMap_IteratorIsNotFound (const LuaHashMapIterator *hash_iterator)
	Returns true if the iterator is "NotFound".

bool	LuaHashMap_IteratorIsEqual (const LuaHashMapIterator hash_iterator1, const LuaHashMapIterator hash_iterator2)
	Returns true if two iterators are equal.

void	LuaHashMap_SetValueStringAtIterator (LuaHashMapIterator restrict hash_iterator, const char restrict value_string)
	Updates a value in the hash table pointed to by the iterator.

void	LuaHashMap_SetValueStringAtIteratorWithLength (LuaHashMapIterator restrict hash_iterator, const char restrict value_string, size_t value_string_length)
	Updates a value in the hash table pointed to by the iterator.

void	LuaHashMap_SetValuePointerAtIterator (LuaHashMapIterator hash_iterator, void value_pointer)
	Updates a value in the hash table pointed to by the iterator.

void	LuaHashMap_SetValueNumberAtIterator (LuaHashMapIterator *hash_iterator, lua_Number value_number)
	Updates a value in the hash table pointed to by the iterator.

void	LuaHashMap_SetValueIntegerAtIterator (LuaHashMapIterator *hash_iterator, lua_Integer value_integer)
	Updates a value in the hash table pointed to by the iterator.

const char *	LuaHashMap_GetValueStringAtIterator (LuaHashMapIterator *hash_iterator)
	Returns the value in the hash table pointed to by the iterator.

const char *	LuaHashMap_GetValueStringAtIteratorWithLength (LuaHashMapIterator restrict hash_iterator, size_t restrict value_string_length_return)
	Returns the value in the hash table pointed to by the iterator.

void *	LuaHashMap_GetValuePointerAtIterator (LuaHashMapIterator *hash_iterator)
	Returns the value in the hash table pointed to by the iterator.

lua_Number	LuaHashMap_GetValueNumberAtIterator (LuaHashMapIterator *hash_iterator)
	Returns the value in the hash table pointed to by the iterator.

lua_Integer	LuaHashMap_GetValueIntegerAtIterator (LuaHashMapIterator *hash_iterator)
	Returns the value in the hash table pointed to by the iterator.

bool	LuaHashMap_ExistsAtIterator (LuaHashMapIterator *hash_iterator)
	Returns whether a key/value pair exists in the hash table pointed to by the iterator.

void	LuaHashMap_RemoveAtIterator (LuaHashMapIterator *hash_iterator)
	Removes a key/value pair in the hash table pointed to by the iterator.

int	LuaHashMap_GetValueTypeAtIterator (LuaHashMapIterator *hash_iterator)
	Returns the type of the value in the hash table pointed to by the iterator.

int	LuaHashMap_GetKeyTypeAtIterator (const LuaHashMapIterator *hash_iterator)
	Returns the type of the key in the iterator.

const char *	LuaHashMap_GetKeyStringAtIterator (const LuaHashMapIterator *hash_iterator)
	Returns the key corresponding to the iterator.

const char *	LuaHashMap_GetKeyStringAtIteratorWithLength (const LuaHashMapIterator restrict hash_iterator, size_t restrict key_string_length_return)
	Returns the key corresponding to the iterator.

size_t	LuaHashMap_GetKeyStringLengthAtIterator (const LuaHashMapIterator *hash_iterator)
	Returns the string length of the key corresponding to the iterator.

void *	LuaHashMap_GetKeyPointerAtIterator (const LuaHashMapIterator *hash_iterator)
	Returns the key corresponding to the iterator.

lua_Number	LuaHashMap_GetKeyNumberAtIterator (const LuaHashMapIterator *hash_iterator)
	Returns the key corresponding to the iterator.

lua_Integer	LuaHashMap_GetKeyIntegerAtIterator (const LuaHashMapIterator *hash_iterator)
	Returns the key corresponding to the iterator.

int	LuaHashMap_GetCachedValueTypeAtIterator (const LuaHashMapIterator *hash_iterator)
	Returns the type of the cached value in the iterator.

const char *	LuaHashMap_GetCachedValueStringAtIterator (const LuaHashMapIterator *hash_iterator)
	Returns the cached value saved in the iterator.

const char *	LuaHashMap_GetCachedValueStringAtIteratorWithLength (const LuaHashMapIterator restrict hash_iterator, size_t restrict value_string_length_return)
	Returns the cached value saved in the iterator.

size_t	LuaHashMap_GetCachedValueStringLengthAtIterator (const LuaHashMapIterator *hash_iterator)
	Returns the string length of the cached value saved in the iterator.

void *	LuaHashMap_GetCachedValuePointerAtIterator (const LuaHashMapIterator *hash_iterator)
	Returns the cached value saved in the iterator.

lua_Number	LuaHashMap_GetCachedValueNumberAtIterator (const LuaHashMapIterator *hash_iterator)
	Returns the cached value saved in the iterator.

lua_Integer	LuaHashMap_GetCachedValueIntegerAtIterator (const LuaHashMapIterator *hash_iterator)
	Returns the cached value saved in the iterator.

Detailed Description

Function Documentation

bool LuaHashMap_ExistsAtIterator ( LuaHashMapIterator * hash_iterator )

Returns whether a key/value pair exists in the hash table pointed to by the iterator.

Parameters

hash_iterator The LuaHashMapIterator instance pointing to the key/value pair

Returns: Returns true if the key/value pair exists in the hash table. Returns false otherwise.

lua_Integer LuaHashMap_GetCachedValueIntegerAtIterator ( const LuaHashMapIterator * hash_iterator )

inline

Returns the cached value saved in the iterator.

Returns the cached value saved in the iterator. integer version This version allows you to specify the string length for the string if you already know it as an optimization.

Parameters

hash_iterator The LuaHashMapIterator instance to operate on.

Returns: Returns the key integer.

Note: This simply pulls the key directly from the struct. This does not involve a full hash look up. If you follow the expected use pattern of the API (as long as you don't modify the hash table behind the back of your iterator), its cached value should be up-to-date, avoiding the need to use the regular GetValue<T>AtIterator which requires another full hash table look up.

lua_Number LuaHashMap_GetCachedValueNumberAtIterator ( const LuaHashMapIterator * hash_iterator )

inline

Returns the cached value saved in the iterator.

Returns the cached value saved in the iterator. integer version This version allows you to specify the string length for the string if you already know it as an optimization.

Parameters

hash_iterator The LuaHashMapIterator instance to operate on.

Returns: Returns the key integer.

Note: This simply pulls the key directly from the struct. This does not involve a full hash look up. If you follow the expected use pattern of the API (as long as you don't modify the hash table behind the back of your iterator), its cached value should be up-to-date, avoiding the need to use the regular GetValue<T>AtIterator which requires another full hash table look up.

void* LuaHashMap_GetCachedValuePointerAtIterator ( const LuaHashMapIterator * hash_iterator )

inline

Returns the cached value saved in the iterator.

Returns the cached value saved in the iterator. pointer version This version allows you to specify the string length for the string if you already know it as an optimization.

Parameters

hash_iterator The LuaHashMapIterator instance to operate on.

Returns: Returns the key pointer.

Note: This simply pulls the key directly from the struct. This does not involve a full hash look up. If you follow the expected use pattern of the API (as long as you don't modify the hash table behind the back of your iterator), its cached value should be up-to-date, avoiding the need to use the regular GetValue<T>AtIterator which requires another full hash table look up.

const char* LuaHashMap_GetCachedValueStringAtIterator ( const LuaHashMapIterator * hash_iterator )

inline

Returns the cached value saved in the iterator.

Returns the cached value saved in the iterator. string version

Parameters

hash_iterator The LuaHashMapIterator instance to operate on.

Returns: Returns the Lua internalized pointer for the key string.

Note: This simply pulls the key directly from the struct. This does not involve a full hash look up. If you follow the expected use pattern of the API (as long as you don't modify the hash table behind the back of your iterator), its cached value should be up-to-date, avoiding the need to use the regular GetValue<T>AtIterator which requires another full hash table look up.

const char* LuaHashMap_GetCachedValueStringAtIteratorWithLength	(	const LuaHashMapIterator *restrict	hash_iterator,
		size_t *restrict	value_string_length_return
	)

inline

Returns the cached value saved in the iterator.

Returns the cached value saved in the iterator. string version This version allows you to specify the string length for the string if you already know it as an optimization.

Parameters

hash_iterator	The LuaHashMapIterator instance to operate on.
value_string_length_return	This returns by reference the string length (strlen()) of the returned key string. You may pass NULL to ignore this result.

Returns: Returns the Lua internalized pointer for the key string.

Note: This simply pulls the key directly from the struct. This does not involve a full hash look up. If you follow the expected use pattern of the API (as long as you don't modify the hash table behind the back of your iterator), its cached value should be up-to-date, avoiding the need to use the regular GetValue<T>AtIterator which requires another full hash table look up.

size_t LuaHashMap_GetCachedValueStringLengthAtIterator ( const LuaHashMapIterator * hash_iterator )

inline

Returns the string length of the cached value saved in the iterator.

Returns the string length of the cached value saved in the current location of the iterator.

Parameters

hash_iterator The LuaHashMapIterator instance to operate on.

Returns: Returns the string length (strlen()) of the key pointer.

Note: This simply pulls the key directly from the struct. This does not involve a full hash look up.

int LuaHashMap_GetCachedValueTypeAtIterator ( const LuaHashMapIterator * hash_iterator )

inline

Returns the type of the cached value in the iterator.

This returns the type (e.g. string, pointer, number) of the cached value in the iterator. The integer return value corresponds directly to Lua's types. Valid values are LUA_TSTRING, LUA_TLIGHTUSERDATA, LUA_TNUMBER. (LUA_TNONE may appear in the case of an error.)

This information is particularly useful if you want to store different types within the same hash table. You can use this information to dynamically discover which type is stored and then call the correct Get<T> function.

Parameters

hash_iterator The LuaHashMapIterator instance to operate on.

Returns: Returns an integer corresponding to Lua's mapping of types. Valid values should be LUA_TSTRING, LUA_TLIGHTUSERDATA, LUA_TNUMBER.

Note: This simply pulls the value type directly from the struct. This does not involve a full hash look up. If you follow the expected use pattern of the API (as long as you don't modify the hash table behind the back of your iterator), its cached value should be up-to-date, avoiding the need to use the regular GetValue<T>AtIterator which requires another full hash table look up.

Warning: (Canonical) Lua does not have a way to distinguish whether the number is a lua_Number or lua_Integer. (It is assumed lua_Number.) If you need to keep integers and floating point distinct, use different hash map instances to keep them separated.

LuaHashMapIterator LuaHashMap_GetIteratorAtBegin ( LuaHashMap * hash_map )

Returns an iterator at the start position of the hash table.

Returns an iterator at the start position of the hash table. This is what you use if you are going to iterate through the entire collection.

Parameters

hash_map The LuaHashMap instance to operate on.

Returns: Returns an iterator at the start position of the hash table. If there is a failure, a "NotFound" iterator will be returned. Use LuaHashMap_IteratorIsNotFound to detect if the iterator is bad.

See Also: LuaHashMap_GetIteratorAtEnd, LuaHashMap_IteratorNext, LuaHashMap_IteratorIsNotFound

LuaHashMapIterator LuaHashMap_GetIteratorAtEnd ( LuaHashMap * hash_map )

Returns an iterator at the end position of the hash table.

Returns an iterator at the end position of the hash table. This is what you use if you are going to iterate through the entire collection.

Parameters

hash_map The LuaHashMap instance to operate on.

Returns: Returns an iterator at the end position of the hash table. If there is a failure, a "NotFound" iterator will be returned. Use LuaHashMap_IteratorIsNotFound to detect if the iterator is bad.

Note: The end iterator doesn't actually point to the last item in the collection. It is actually one item past the end. It is analgous to a null/termination character in a string. So don't try to get the key or value from the end iterator because it won't give you anything useful.

for(LuaHashMapIterator hash_iterator = LuaHashMap_GetIteratorAtBegin(hash_map), hash_iterator_end = LuaHashMap_GetIteratorAtEnd(hash_map);
    ! LuaHashMap_IteratorIsEqual(&hash_iterator, &hash_iterator_end);
    LuaHashMap_IteratorNext(&hash_iterator)
)
{
    fprintf(stderr, "Price of %s: %lf\n", 
            LuaHashMap_GetKeyStringAtIterator(&hash_iterator), 
            LuaHashMap_GetCachedValueNumberAtIterator(&hash_iterator));
}

See Also: LuaHashMap_IteratorNext, LuaHashMap_GetIteratorAtBegin, LuaHashMap_IteratorIsNotFound, LuaHashMap_IteratorIsEqual

LuaHashMapIterator LuaHashMap_GetIteratorForKeyInteger	(	LuaHashMap *	hash_map,
		lua_Integer	key_integer
	)

Returns an iterator corresponding to the specified key.

This returns an iterator corresponding to the specified key. integer version

The intent of this method is to allow you to do multiple operations at the current position without doing unnecessary additional hash look ups. The most common example is you want to test to see if a key/value pair actually exists in the hash table before trying to retrive the value. Using the GetIteratorForKey function, you do one hash lookup, and then you can test existence and extract the CachedValue from the iterator without any subsequent hash look ups.

Parameters

hash_map	The LuaHashMap instance to operate on
key_integer	The key for the key/value pair

Returns: Returns an iterator at the position of the specified key. If there is a failure, a "NotFound" iterator will be returned. Use LuaHashMap_IteratorIsNotFound to detect if the iterator is bad.

// This is the one hash look up.
LuaHashMapIterator hash_iterator = LuaHashMap_GetIteratorForKeyPointer(hash_map, fooptr);
bool exists = LuaHashMap_ExistsAtIterator(&hash_iterator);
// This information is in the iterator itself which avoids another hash lookup.
if(exists)
{
    fprintf(stderr, "The value for key=fooptr exists: %lf\n", LuaHashMap_GetCachedValueNumberAtIterator(&hash_iterator));
}
else
{
    fprintf(stderr, "The key/value pair for key=fooptr does not exist\n");
}

See Also: LuaHashMap_ExistsAtIterator, LuaHashMap_GetIteratorAtBegin, LuaHashMap_IteratorIsNotFound

LuaHashMapIterator LuaHashMap_GetIteratorForKeyNumber	(	LuaHashMap *	hash_map,
		lua_Number	key_number
	)

Returns an iterator corresponding to the specified key.

This returns an iterator corresponding to the specified key. number version

The intent of this method is to allow you to do multiple operations at the current position without doing unnecessary additional hash look ups. The most common example is you want to test to see if a key/value pair actually exists in the hash table before trying to retrive the value. Using the GetIteratorForKey function, you do one hash lookup, and then you can test existence and extract the CachedValue from the iterator without any subsequent hash look ups.

Parameters

hash_map	The LuaHashMap instance to operate on
key_number	The key for the key/value pair

Returns: Returns an iterator at the position of the specified key. If there is a failure, a "NotFound" iterator will be returned. Use LuaHashMap_IteratorIsNotFound to detect if the iterator is bad.

// This is the one hash look up.
LuaHashMapIterator hash_iterator = LuaHashMap_GetIteratorForKeyPointer(hash_map, fooptr);
bool exists = LuaHashMap_ExistsAtIterator(&hash_iterator);
// This information is in the iterator itself which avoids another hash lookup.
if(exists)
{
    fprintf(stderr, "The value for key=fooptr exists: %lf\n", LuaHashMap_GetCachedValueNumberAtIterator(&hash_iterator));
}
else
{
    fprintf(stderr, "The key/value pair for key=fooptr does not exist\n");
}

See Also: LuaHashMap_ExistsAtIterator, LuaHashMap_GetIteratorAtBegin, LuaHashMap_IteratorIsNotFound

LuaHashMapIterator LuaHashMap_GetIteratorForKeyPointer	(	LuaHashMap *	hash_map,
		void *	key_pointer
	)

Returns an iterator corresponding to the specified key.

This returns an iterator corresponding to the specified key. pointer version

The intent of this method is to allow you to do multiple operations at the current position without doing unnecessary additional hash look ups. The most common example is you want to test to see if a key/value pair actually exists in the hash table before trying to retrive the value. Using the GetIteratorForKey function, you do one hash lookup, and then you can test existence and extract the CachedValue from the iterator without any subsequent hash look ups.

Parameters

hash_map	The LuaHashMap instance to operate on
key_pointer	The key for the key/value pair

Returns: Returns an iterator at the position of the specified key. If there is a failure, a "NotFound" iterator will be returned. Use LuaHashMap_IteratorIsNotFound to detect if the iterator is bad.

// This is the one hash look up.
LuaHashMapIterator hash_iterator = LuaHashMap_GetIteratorForKeyPointer(hash_map, fooptr);
bool exists = LuaHashMap_ExistsAtIterator(&hash_iterator);
// This information is in the iterator itself which avoids another hash lookup.
if(exists)
{
    fprintf(stderr, "The value for key=fooptr exists: %lf\n", LuaHashMap_GetCachedValueNumberAtIterator(&hash_iterator));
}
else
{
    fprintf(stderr, "The key/value pair for key=fooptr does not exist\n");
}

See Also: LuaHashMap_ExistsAtIterator, LuaHashMap_GetIteratorAtBegin, LuaHashMap_IteratorIsNotFound

LuaHashMapIterator LuaHashMap_GetIteratorForKeyString	(	LuaHashMap *restrict	hash_map,
		const char *restrict	key_string
	)

Returns an iterator corresponding to the specified key.

This returns an iterator corresponding to the specified key. string version

The intent of this method is to allow you to do multiple operations at the current position without doing unnecessary additional hash look ups. The most common example is you want to test to see if a key/value pair actually exists in the hash table before trying to retrive the value. Using the GetIteratorForKey function, you do one hash lookup, and then you can test existence and extract the CachedValue from the iterator without any subsequent hash look ups.

Parameters

hash_map	The LuaHashMap instance to operate on
key_string	The key for the key/value pair

Returns: Returns an iterator at the position of the specified key. If there is a failure, a "NotFound" iterator will be returned. Use LuaHashMap_IteratorIsNotFound to detect if the iterator is bad.

// This is the one hash look up.
LuaHashMapIterator hash_iterator = LuaHashMap_GetIteratorForKeyString(hash_map, "foo");
// Thie remaining information is in the iterator itself which avoids another hash lookup.
bool exists = LuaHashMap_ExistsAtIterator(&hash_iterator);
if(exists)
{
    fprintf(stderr, "The value for key="foo" exists: %lf\n", LuaHashMap_GetCachedValueNumberAtIterator(&hash_iterator));
}
else
{
    fprintf(stderr, "The key/value pair for key="foo" does not exist\n");
}

See Also: LuaHashMap_ExistsAtIterator, LuaHashMap_GetIteratorAtBegin, LuaHashMap_IteratorIsNotFound, LuaHashMap_GetIteratorForKeyStringWithLength

LuaHashMapIterator LuaHashMap_GetIteratorForKeyStringWithLength	(	LuaHashMap *restrict	hash_map,
		const char *restrict	key_string,
		size_t	key_string_length
	)

Returns an iterator corresponding to the specified key.

This returns an iterator corresponding to the specified key. string version This version allows you to specify the string length for the string if you already know it as an optimization.

The intent of this method is to allow you to do multiple operations at the current position without doing unnecessary additional hash look ups. The most common example is you want to test to see if a key/value pair actually exists in the hash table before trying to retrive the value. Using the GetIteratorForKey function, you do one hash lookup, and then you can test existence and extract the CachedValue from the iterator without any subsequent hash look ups.

Parameters

hash_map	The LuaHashMap instance to operate on
key_string	The key for the key/value pair
key_string_length	The string length (strlen()) of the key string. (This does not count the \0 terminator character.)

Returns: Returns an iterator at the position of the specified key. If there is a failure, a "NotFound" iterator will be returned. Use LuaHashMap_IteratorIsNotFound to detect if the iterator is bad.

// This is the one hash look up.
size_t key_string_length;
LuaHashMapIterator hash_iterator = LuaHashMap_GetIteratorForKeyStringWithLength(hash_map, "foo", &key_string_length);
bool exists = LuaHashMap_ExistsAtIterator(&hash_iterator);
// This information is in the iterator itself which avoids another hash lookup.
if(exists)
{
    fprintf(stderr, "The value for key="foo" exists: %lf\n", LuaHashMap_GetCachedValueNumberAtIterator(&hash_iterator));
}
else
{
    fprintf(stderr, "The key/value pair for key="foo" does not exist\n");
}

See Also: LuaHashMap_ExistsAtIterator, LuaHashMap_GetIteratorAtBegin, LuaHashMap_IteratorIsNotFound, LuaHashMap_GetIteratorForKeyString

lua_Integer LuaHashMap_GetKeyIntegerAtIterator ( const LuaHashMapIterator * hash_iterator )

inline

Returns the key corresponding to the iterator.

Returns the key corresponding to the current location of the iterator. integer version

Parameters

hash_iterator The LuaHashMapIterator instance to operate on.

Returns: Returns the key integer.

Note: This simply pulls the key directly from the struct. This does not involve a full hash look up.

lua_Number LuaHashMap_GetKeyNumberAtIterator ( const LuaHashMapIterator * hash_iterator )

inline

Returns the key corresponding to the iterator.

Returns the key corresponding to the current location of the iterator. number version

Parameters

hash_iterator The LuaHashMapIterator instance to operate on.

Returns: Returns the key number.

Note: This simply pulls the key directly from the struct. This does not involve a full hash look up.

void* LuaHashMap_GetKeyPointerAtIterator ( const LuaHashMapIterator * hash_iterator )

inline

Returns the key corresponding to the iterator.

Returns the key corresponding to the current location of the iterator. pointer version

Parameters

hash_iterator The LuaHashMapIterator instance to operate on.

Returns: Returns the key pointer.

Note: This simply pulls the key directly from the struct. This does not involve a full hash look up.

const char* LuaHashMap_GetKeyStringAtIterator ( const LuaHashMapIterator * hash_iterator )

inline

Returns the key corresponding to the iterator.

Returns the key corresponding to the current location of the iterator. string version This version allows you to specify the string length for the string if you already know it as an optimization.

Parameters

hash_iterator The LuaHashMapIterator instance to operate on.

Returns: Returns the Lua internalized pointer for the key string.

Note: This simply pulls the key directly from the struct. This does not involve a full hash look up.

const char* LuaHashMap_GetKeyStringAtIteratorWithLength	(	const LuaHashMapIterator *restrict	hash_iterator,
		size_t *restrict	key_string_length_return
	)

inline

Returns the key corresponding to the iterator.

Returns the key corresponding to the current location of the iterator. string version This version allows you to specify the string length for the string if you already know it as an optimization.

Parameters

hash_iterator	The LuaHashMapIterator instance to operate on.
key_string_length_return	This returns by reference the string length (strlen()) of the returned key string. You may pass NULL to ignore this result.

Returns: Returns the Lua internalized pointer for the key string.

Note: This simply pulls the key directly from the struct. This does not involve a full hash look up.

size_t LuaHashMap_GetKeyStringLengthAtIterator ( const LuaHashMapIterator * hash_iterator )

inline

Returns the string length of the key corresponding to the iterator.

Returns the string length of the key corresponding to the current location of the iterator.

Parameters

hash_iterator The LuaHashMapIterator instance to operate on.

Returns: Returns the string length (strlen()) of the key pointer.

Note: This simply pulls the key directly from the struct. This does not involve a full hash look up.

int LuaHashMap_GetKeyTypeAtIterator ( const LuaHashMapIterator * hash_iterator )

inline

Returns the type of the key in the iterator.

This returns the type (e.g. string, pointer, number) of the key in the iterator. The integer return value corresponds directly to Lua's types. Valid values are LUA_TSTRING, LUA_TLIGHTUSERDATA, LUA_TNUMBER. (LUA_TNONE may appear in the case of an error.)

This information is particularly useful if you want to store different types within the same hash table. You can use this information to dynamically discover which type is stored and then call the correct Get<T> function.

Parameters

hash_iterator The LuaHashMapIterator instance to operate on.

Returns: Returns an integer corresponding to Lua's mapping of types. Valid values should be LUA_TSTRING, LUA_TLIGHTUSERDATA, LUA_TNUMBER.

Note: This simply pulls the key type directly from the struct. This does not involve a full hash look up.

Warning: (Canonical) Lua does not have a way to distinguish whether the number is a lua_Number or lua_Integer. (It is assumed lua_Number.) If you need to keep integers and floating point distinct, use different hash map instances to keep them separated.

lua_Integer LuaHashMap_GetValueIntegerAtIterator ( LuaHashMapIterator * hash_iterator )

Returns the value in the hash table pointed to by the iterator.

Returns the value in the hash table pointed to by the iterator. pointer version

Parameters

hash_iterator The LuaHashMapIterator instance pointing to the key/value pair you want to retrieve.

Returns: Returns the value for the key.

Note: If you follow the expected use pattern of the API, then you generally don't need to call this function and you want the CachedValue version of this function. As long as you don't modify the hash table behind the back of your iterator, its cached value should be up-to-date, avoiding the need for another full hash table look up.

See Also: LuaHashMap_GetCachedValuePointerAtIterator

lua_Number LuaHashMap_GetValueNumberAtIterator ( LuaHashMapIterator * hash_iterator )

Returns the value in the hash table pointed to by the iterator.

Returns the value in the hash table pointed to by the iterator. pointer version

Parameters

hash_iterator The LuaHashMapIterator instance pointing to the key/value pair you want to retrieve.

Returns: Returns the value for the key.

Note: If you follow the expected use pattern of the API, then you generally don't need to call this function and you want the CachedValue version of this function. As long as you don't modify the hash table behind the back of your iterator, its cached value should be up-to-date, avoiding the need for another full hash table look up.

See Also: LuaHashMap_GetCachedValuePointerAtIterator

void* LuaHashMap_GetValuePointerAtIterator ( LuaHashMapIterator * hash_iterator )

Returns the value in the hash table pointed to by the iterator.

Returns the value in the hash table pointed to by the iterator. pointer version

Parameters

hash_iterator The LuaHashMapIterator instance pointing to the key/value pair you want to retrieve.

Returns: Returns the value for the key.

Note: If you follow the expected use pattern of the API, then you generally don't need to call this function and you want the CachedValue version of this function. As long as you don't modify the hash table behind the back of your iterator, its cached value should be up-to-date, avoiding the need for another full hash table look up.

See Also: LuaHashMap_GetCachedValuePointerAtIterator

const char* LuaHashMap_GetValueStringAtIterator ( LuaHashMapIterator * hash_iterator )

Returns the value in the hash table pointed to by the iterator.

Returns the value in the hash table pointed to by the iterator. string version

Parameters

hash_iterator The LuaHashMapIterator instance pointing to the key/value pair you want to retrieve.

Returns: Returns the Lua internalized pointer for the key string.

Note: If you follow the expected use pattern of the API, then you generally don't need to call this function and you want the CachedValue version of this function. As long as you don't modify the hash table behind the back of your iterator, its cached value should be up-to-date, avoiding the need for another full hash table look up.

See Also: LuaHashMap_GetCachedValueStringAtIterator, LuaHashMap_GetValueStringAtIteratorWithLength

const char* LuaHashMap_GetValueStringAtIteratorWithLength	(	LuaHashMapIterator *restrict	hash_iterator,
		size_t *restrict	value_string_length_return
	)

Returns the value in the hash table pointed to by the iterator.

Returns the value in the hash table pointed to by the iterator. string version This version allows you to specify the string length for the string if you already know it as an optimization.

Parameters

hash_iterator	The LuaHashMapIterator instance pointing to the key/value pair you want to retrieve.
value_string_length_return	This returns by reference the string length (strlen()) of the returned value string. You may pass NULL to ignore this result.

Returns: Returns the Lua internalized pointer for the key string.

Note: If you follow the expected use pattern of the API, then you generally don't need to call this function and you want the CachedValue version of this function. As long as you don't modify the hash table behind the back of your iterator, its cached value should be up-to-date, avoiding the need for another full hash table look up.

See Also: LuaHashMap_GetCachedValueStringAtIteratorWithLength, LuaHashMap_GetValueStringAtIterator

int LuaHashMap_GetValueTypeAtIterator ( LuaHashMapIterator * hash_iterator )

Returns the type of the value in the hash table pointed to by the iterator.

This returns the type (e.g. string, pointer, number) of the value in the hash table pointed to by the iterator. The integer return value corresponds directly to Lua's types. Valid values are LUA_TSTRING, LUA_TLIGHTUSERDATA, LUA_TNUMBER. (LUA_TNONE may appear in the case of an error.)

This information is particularly useful if you want to store different types within the same hash table. You can use this information to dynamically discover which type is stored and then call the correct Get<T> function.

Parameters

hash_iterator The LuaHashMapIterator instance to operate on.

Returns: Returns an integer corresponding to Lua's mapping of types. Valid values should be LUA_TSTRING, LUA_TLIGHTUSERDATA, LUA_TNUMBER.

Note: This version does a full hash look up to retrieve the value. Use LuaHashMap_GetCachedValueTypeAtIterator to avoid a full look up.

Warning: (Canonical) Lua does not have a way to distinguish whether the number is a lua_Number or lua_Integer. (It is assumed lua_Number.) If you need to keep integers and floating point distinct, use different hash map instances to keep them separated.

See Also: LuaHashMap_GetCachedValueTypeAtIterator

bool LuaHashMap_IteratorIsEqual	(	const LuaHashMapIterator *	hash_iterator1,
		const LuaHashMapIterator *	hash_iterator2
	)

Returns true if two iterators are equal.

Returns true if two iterators are equal. This generally means they are pointing to the same key/value pair in the same hash table.

Parameters

hash_iterator1	The first iterator that will be compared.
hash_iterator2	The other iterator that will be compared.

Returns: Returns true if the iterators are equal.

bool LuaHashMap_IteratorIsNotFound ( const LuaHashMapIterator * hash_iterator )

inline

Returns true if the iterator is "NotFound".

Returns true if the iterator is bad (i.e. you tried to get an iterator for a key that doesn't exist).

Parameters

hash_iterator The LuaHashMapIterator instance to operate on.

Returns: Returns true if the iterator is "NotFound" or bad.

Note: End iterators are considered valid iterators and this function will return false on this case.

bool LuaHashMap_IteratorNext ( LuaHashMapIterator * hash_iterator )

Increments the iterator to the next item in the hash table.

Parameters

hash_iterator The LuaHashMapIterator instance to operate on.

Returns: Returns true if the iterator successfully went to the next item. False otherwise. This can be useful to know when to stop looping in a control loop.
// This pattern is good if you know you have at least one item in the hash.

LuaHashMapIterator hash_iterator = LuaHashMap_GetIteratorAtBegin(hash_map);

do

{

fprintf(stderr, "Price of %s: %lf\n",

LuaHashMap_GetKeyStringAtIterator(&hash_iterator),

LuaHashMap_GetCachedValueNumberAtIterator(&hash_iterator));

} while(LuaHashMap_IteratorNext(&hash_iterator));

See Also: LuaHashMap_GetIteratorAtEnd, LuaHashMap_GetIteratorAtBegin, LuaHashMap_IteratorIsNotFound

void LuaHashMap_RemoveAtIterator ( LuaHashMapIterator * hash_iterator )

Removes a key/value pair in the hash table pointed to by the iterator.

Parameters

hash_iterator The LuaHashMapIterator instance pointing to the key/value pair

void LuaHashMap_SetValueIntegerAtIterator	(	LuaHashMapIterator *	hash_iterator,
		lua_Integer	value_integer
	)

Updates a value in the hash table pointed to by the iterator.

Updates a value in the hash table pointed to by the iterator. The iterator must be a valid iterator (i.e. the key it points to must already be in the hash table). This will not insert new key/value pairs into the hash table. integer version

Parameters

hash_iterator	The LuaHashMapIterator instance pointing to the key/value pair you want to update the value to.
value_integer	The value for the key. NULL key pointers are allowed as legitimate values.

void LuaHashMap_SetValueNumberAtIterator	(	LuaHashMapIterator *	hash_iterator,
		lua_Number	value_number
	)

Updates a value in the hash table pointed to by the iterator.

Updates a value in the hash table pointed to by the iterator. The iterator must be a valid iterator (i.e. the key it points to must already be in the hash table). This will not insert new key/value pairs into the hash table. number version

Parameters

hash_iterator	The LuaHashMapIterator instance pointing to the key/value pair you want to update the value to.
value_number	The value for the key. NULL key pointers are allowed as legitimate values.

void LuaHashMap_SetValuePointerAtIterator	(	LuaHashMapIterator *	hash_iterator,
		void *	value_pointer
	)

Updates a value in the hash table pointed to by the iterator.

Updates a value in the hash table pointed to by the iterator. The iterator must be a valid iterator (i.e. the key it points to must already be in the hash table). This will not insert new key/value pairs into the hash table. pointer version

Parameters

hash_iterator	The LuaHashMapIterator instance pointing to the key/value pair you want to update the value to.
value_pointer	The value for the key. NULL key pointers are allowed as legitimate values.

void LuaHashMap_SetValueStringAtIterator	(	LuaHashMapIterator *restrict	hash_iterator,
		const char *restrict	value_string
	)

Updates a value in the hash table pointed to by the iterator.

Updates a value in the hash table pointed to by the iterator. The iterator must be a valid iterator (i.e. the key it points to must already be in the hash table). This will not insert new key/value pairs into the hash table. string version

Parameters

hash_iterator	The LuaHashMapIterator instance pointing to the key/value pair you want to update the value to.
value_string	The value for the key. NULL value strings are treated as strings with length=0 ("").

Note: Lua copies strings and internalizes them. This means Lua/LuaHashMap have its own copy of the string and you are free to delete your string if you are done with it.

See Also: LuaHashMap_SetValueStringAtIteratorWithLength

void LuaHashMap_SetValueStringAtIteratorWithLength	(	LuaHashMapIterator *restrict	hash_iterator,
		const char *restrict	value_string,
		size_t	value_string_length
	)

Updates a value in the hash table pointed to by the iterator.

Updates a value in the hash table pointed to by the iterator. The iterator must be a valid iterator (i.e. the key it points to must already be in the hash table). This will not insert new key/value pairs into the hash table. string version This version allows you to specify the string length for each string if you already know it as an optimization.

Parameters

hash_iterator	The LuaHashMapIterator instance pointing to the key/value pair you want to update the value to.
value_string	The value for the key. NULL value strings are treated as strings with length=0 ("").
value_string_length	The string length (strlen()) of the value string. (This does not count the \0 terminator character.)

Note: Lua copies strings and internalizes them. This means Lua/LuaHashMap have its own copy of the string and you are free to delete your string if you are done with it.

See Also: LuaHashMap_SetValueStringAtIterator

Functions

Detailed Description

Function Documentation