| Updated: April 19, 2023 |
A dictionary object is a collection of key-value pairs. Each pair is considered an entry or a named value, where the key acts as the entry's name. Keys are unique, so you can't add an entry with a duplicate key.
The Dictionary Object API allows you to specify keys and values as C-strings or as shareable strings. Using C-strings is convenient but using shareable strings may be more efficient, especially if you use the same keys and values in multiple program components.
A shareable string is a data structure that stores a string and keeps track of how many handles to it exist. This design allows you to clone shareable string handles and have separate components take ownership of individual handles so they can use the string independently of each other, without copying all of the string characters. It also allows the libstrm library to safely destroy the string when the last handle is destroyed, without impacting other components. Note that in dictionaries, both the keys and values are stored in shareable strings.
The API allows you to create multiple handles to a dictionary object and then use and even delete these handles in independent components. After it's created, a dictionary is immutable until it's destroyed, so separate components can access it through their own handles and read the exact same entries, without worrying that the dictionary could change between reads.