# toy_literal_dictionary.h

This header defines the dictionary structure (as well as the private entry structure), which manages a series of `Toy_Literal` instances stored in a key-value hash map. The dictionary does not take ownership of given literals, instead it makes an internal copy.

The dictionary type is one of two fundemental data structures used throughout Toy - the other is the array.

## Defined Macros

### TOY_DICTIONARY_MAX_LOAD

If the contents of a dictionary exceeds this percentage of it's capacity, then a new buffer is created, the old contents are copied over one-by-one, and the original buffer is freed.

Since this process can be memory and time intensive, a configurable macro is used to allow for fine-grained control across the lang.

The current default value is `0.75`, representing 75% capacity.

## Defined Functions

### void Toy_initLiteralDictionary(Toy_LiteralDictionary* dictionary)

This function initializes the `Toy_LiteralDictionary` pointed to by `dictionary`.

### void Toy_freeLiteralDictionary(Toy_LiteralDictionary* dictionary)

This function frees a `Toy_LiteralDictionary` pointed to by `dictionary`. Every literal within is passed to `Toy_freeLiteral()` before its memory is released.

### void Toy_setLiteralDictionary(Toy_LiteralDictionary* dictionary, Toy_Literal key, Toy_Literal value)

This function inserts the given key-value pair of literals into `dictionary`, creating it if it doesn't exist, or freeing and overwriting it if `key` is already present. This function may also expand the memory buffer if needed.

When expanding the memory buffer, a full copy of the existing dictionary's contents is created - this can be memory intensive.

Literal functions and opaques cannot be used as keys.

### Toy_Literal Toy_getLiteralDictionary(Toy_LiteralDictionary* dictionary, Toy_Literal key)

This function returns the value of the literal within `dictionary` identified by `key`, or a null literal if it doesn't exist.

Literal functions and opaques cannot be used as keys.

### void Toy_removeLiteralDictionary(Toy_LiteralDictionary* dictionary, Toy_Literal key)

This function removes the key-value pair of literals from `dictionary` identified by `key`, if it exists.

Literal functions and opaques cannot be used as keys.

### bool Toy_existsLiteralDictionary(Toy_LiteralDictionary* dictionary, Toy_Literal key)

This function returns true if the key-value pair identified by `key` exists within `dictionary`, otherwise it returns false.