strm_string_t

Library:

Description:

The strm_string_t structure is a private data type representing a shareable string object. Pointers to this data type are used as handles to shareable strings in API functions.

You can create a new shareable string containing a specific C-string by calling strm_string_make(). This function returns a shareable string handle that can you use to define a key or value when building a dictionary. You can also obtain a pointer to the first character in the string, create a new shareable string, or destroy the shareable string.

Different shareable string handles may be represented by identical pointers; you should not compare handles. Regardless of how handles are represented internally, you must call strm_string_destroy() separately for each handle that you own to properly dispose of any resources associated with it. Some API calls take ownership of (consume) a shareable string handle passed in as an argument. Their function descriptions state when they do this. In these cases, you shouldn't destroy the handle; the library will do so when appropriate.

Only when the last handle to a shareable string gets destroyed does the library free the object's memory (because it's now safe to do so).