Defined in carb/dictionary/DictionaryUtils.h

inline Item *carb::dictionary::createDictionaryFromFile(ISerializer *serializer, const char *filename)

Attempts to read the contents of a file into a dictionary.


This attempts to parse a dictionary data from a file. The format that the file’s data is parsed from will be implied by the specific implementation of the ISerializer interface that is passed in. The data found in the file will be parsed into a full dictionary hierarchy if it is parsed correctly. If the file contains a syntax error, the specific result (ie: full failure vs partial success) is determined by the specific behavior of the ISerializer interface.

Thread Safety

This operation is thread safe.

  • serializer[in] The ISerializer interface to use to parse the data in the file. This serializer must be able to parse the assumed format of the named file (ie: JSON or TOML). This must not be nullptr. Note that this interface will internally depend on only a single implementation of the IDictionary interface having been loaded. If multiple implementations are available, this operation will be likely to result in undefined behavior.

  • filename[in] The name of the file to parse in the format assumed by the serializer interface serializer. This must not be nullptr.


A new dictionary item containing the information parsed from the file filename if it is successfully opened, read, and parsed. When no longer needed, this must be passed to IDictionary::destroyItem() to destroy it. Returns nullptr if the file does not exit, could not be opened, or a parsing error occurred.