## hb-blob

hb-blob

## Synopsis

    hb_blob_t *         hb_blob_create                      (const char *data,
                                                             unsigned int length,
                                                             hb_memory_mode_t mode,
                                                             void *user_data,
                                                             hb_destroy_func_t destroy);
    hb_blob_t *         hb_blob_create_sub_blob             (hb_blob_t *parent,
                                                             unsigned int offset,
                                                             unsigned int length);
    void                hb_blob_destroy                     (hb_blob_t *blob);
    const char *        hb_blob_get_data                    (hb_blob_t *blob,
                                                             unsigned int *length);
    char *              hb_blob_get_data_writable           (hb_blob_t *blob,
                                                             unsigned int *length);
    hb_blob_t *         hb_blob_get_empty                   (void);
    unsigned int        hb_blob_get_length                  (hb_blob_t *blob);
    void *              hb_blob_get_user_data               (hb_blob_t *blob,
                                                             hb_user_data_key_t *key);
    hb_bool_t           hb_blob_is_immutable                (hb_blob_t *blob);
    void                hb_blob_make_immutable              (hb_blob_t *blob);
    hb_blob_t *         hb_blob_reference                   (hb_blob_t *blob);
    hb_bool_t           hb_blob_set_user_data               (hb_blob_t *blob,
                                                             hb_user_data_key_t *key,
                                                             void *data,
                                                             hb_destroy_func_t destroy,
                                                             hb_bool_t replace);
    typedef             hb_blob_t;
    enum                hb_memory_mode_t;

## Description

## Details

### hb_blob_create ()

    hb_blob_t *         hb_blob_create                      (const char *data,
                                                             unsigned int length,
                                                             hb_memory_mode_t mode,
                                                             void *user_data,
                                                             hb_destroy_func_t destroy);

### hb_blob_create_sub_blob ()

    hb_blob_t *         hb_blob_create_sub_blob             (hb_blob_t *parent,
                                                             unsigned int offset,
                                                             unsigned int length);

Returns a blob that represents a range of bytes in `parent`. The new blob is always created with `HB_MEMORY_MODE_READONLY`, meaning that it will never modify data in the parent blob. The parent data is not expected to be modified, and will result in undefined behavior if it is.

Makes `parent` immutable.

`parent` : | Parent blob.
`offset` : | Start offset of sub-blob within `parent`, in bytes.
`length` : | Length of sub-blob.
Returns : | New blob, or the empty blob if something failed or if `length` is zero or `offset` is beyond the end of `parent`'s data. Destroy with `hb_blob_destroy()`.

Since 1.0

### hb_blob_destroy ()

    void                hb_blob_destroy                     (hb_blob_t *blob);

Descreases the reference count on `blob`, and if it reaches zero, destroys `blob`, freeing all memory, possibly calling the destroy-callback the blob was created for if it has not been called already.

See TODO:link object types for more information.

`blob` : | a blob.

Since 1.0

### hb_blob_get_data ()

    const char *        hb_blob_get_data                    (hb_blob_t *blob,
                                                             unsigned int *length);

`blob` : | a blob.
`length` : | . [out]
Returns : | . [transfer none][array length=length]

Since 1.0

### hb_blob_get_data_writable ()

    char *              hb_blob_get_data_writable           (hb_blob_t *blob,
                                                             unsigned int *length);

Tries to make blob data writable (possibly copying it) and return pointer to data.

Fails if blob has been made immutable, or if memory allocation fails.

`blob` : | a blob.
`length` : | output length of the writable data. [out]
Returns : | Writable blob data, or `NULL` if failed. [transfer none][array length=length]

Since 1.0

### hb_blob_get_empty ()

    hb_blob_t *         hb_blob_get_empty                   (void);

Returns the singleton empty blob.

See TODO:link object types for more information.

Returns : | the empty blob. [transfer full]

Since 1.0

### hb_blob_get_length ()

    unsigned int        hb_blob_get_length                  (hb_blob_t *blob);

`blob` : | a blob.
Returns : | the length of blob data in bytes.

Since 1.0

### hb_blob_get_user_data ()

    void *              hb_blob_get_user_data               (hb_blob_t *blob,
                                                             hb_user_data_key_t *key);

`blob` : | a blob.
`key` : | key for data to get.
Returns : | . [transfer none]

Since 1.0

### hb_blob_is_immutable ()

    hb_bool_t           hb_blob_is_immutable                (hb_blob_t *blob);

`blob` : | a blob.
Returns : | TODO

Since 1.0

### hb_blob_make_immutable ()

    void                hb_blob_make_immutable              (hb_blob_t *blob);

`blob` : | a blob.

Since 1.0

### hb_blob_reference ()

    hb_blob_t *         hb_blob_reference                   (hb_blob_t *blob);

Increases the reference count on `blob`.

See TODO:link object types for more information.

`blob` : | a blob.
Returns : | `blob`.

Since 1.0

### hb_blob_set_user_data ()

    hb_bool_t           hb_blob_set_user_data               (hb_blob_t *blob,
                                                             hb_user_data_key_t *key,
                                                             void *data,
                                                             hb_destroy_func_t destroy,
                                                             hb_bool_t replace);

`blob` : | a blob.
`key` : | key for data to set.
`data` : | data to set.
`destroy` : | callback to call when `data` is not needed anymore.
`replace` : | whether to replace an existing data with the same key.

Since 1.0

### hb_blob_t

    typedef struct hb_blob_t hb_blob_t;

### enum hb_memory_mode_t

    typedef enum {
      HB_MEMORY_MODE_DUPLICATE,
      HB_MEMORY_MODE_READONLY,
      HB_MEMORY_MODE_WRITABLE,
      HB_MEMORY_MODE_READONLY_MAY_MAKE_WRITABLE
    } hb_memory_mode_t;

`HB_MEMORY_MODE_DUPLICATE` |
`HB_MEMORY_MODE_READONLY` |
`HB_MEMORY_MODE_WRITABLE` |
`HB_MEMORY_MODE_READONLY_MAY_MAKE_WRITABLE` |