## hb-blob

hb-blob

## Functions

hb_blob_t * | hb_blob_create ()
hb_blob_t * | hb_blob_create_sub_blob ()
void | hb_blob_destroy ()
const char * | hb_blob_get_data ()
char * | hb_blob_get_data_writable ()
hb_blob_t * | hb_blob_get_empty ()
unsigned int | hb_blob_get_length ()
void * | hb_blob_get_user_data ()
hb_bool_t | hb_blob_is_immutable ()
void | hb_blob_make_immutable ()
hb_blob_t * | hb_blob_reference ()
hb_bool_t | hb_blob_set_user_data ()

## Types and Values

typedef | hb_blob_t
enum | hb_memory_mode_t

## Object Hierarchy

        GBoxed
        ╰── hb_blob_t
        GEnum
        ╰── hb_memory_mode_t

## Description

## Functions

### 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);

Creates a new "blob" object wrapping `data` . The `mode` parameter is used to negotiate ownership and lifecycle of `data` .

#### Parameters

data | Pointer to blob data. |
length | Length of `data` in bytes. |
mode | Memory mode for `data` . |
user_data | Data parameter to pass to `destroy` . |
destroy | Callback to call when `data` is not needed anymore. |

#### Returns

New blob, or the empty blob if something failed or if `length` is zero. Destroy with `hb_blob_destroy()`.

Since 1.0

### 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.

#### Parameters

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.

#### Parameters

blob | a blob. |

Since 1.0

### hb_blob_get_data ()

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

#### Parameters

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.

#### Parameters

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);

#### Parameters

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);

#### Parameters

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);

#### Parameters

blob | a blob. |

#### Returns

TODO

Since 1.0

### hb_blob_make_immutable ()

    void
    hb_blob_make_immutable (hb_blob_t *blob);

#### Parameters

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.

#### Parameters

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);

#### Parameters

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. |

#### Returns

Since 1.0

## Types and Values

### hb_blob_t

    typedef struct hb_blob_t hb_blob_t;

### enum hb_memory_mode_t

#### Members

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