User data

To better integrate with client programs, HarfBuzz's objects offer a "user data" mechanism that can be used to attach arbitrary data to the object. User-data attachment can be useful for tying the lifecycles of various pieces of data together, or for creating language bindings.

Each object type has a set_user_data() method and a get_user_data() method. The set_user_data() methods take a client-provided key and a pointer, user_data, pointing to the data itself. Once the key-data pair has been attached to the object, the get_user_data() method can be called with the key, returning the user_data pointer.

The set_user_data() methods also support an optional destroy callback. Client programs can set the destroy callback and receive notification from HarfBuzz whenever the object is destructed.

Finally, each set_user_data() method allows the client program to set a replace Boolean indicating whether or not the function call should replace any existing user_data associated with the specified key.