camel-name-value-array: Camel Reference Manual

## camel-name-value-array camel-name-value-array |

## Functions

CamelNameValueArray * | camel_name_value_array_new ()
CamelNameValueArray * | camel_name_value_array_new_sized ()
CamelNameValueArray * | camel_name_value_array_copy ()
void | camel_name_value_array_free ()
guint | camel_name_value_array_get_length ()
gboolean | camel_name_value_array_get ()
const gchar * | camel_name_value_array_get_named ()
const gchar * | camel_name_value_array_get_name ()
const gchar * | camel_name_value_array_get_value ()
void | camel_name_value_array_append ()
gboolean | camel_name_value_array_set ()
gboolean | camel_name_value_array_set_name ()
gboolean | camel_name_value_array_set_value ()
gboolean | camel_name_value_array_set_named ()
gboolean | camel_name_value_array_remove ()
guint | camel_name_value_array_remove_named ()
void | camel_name_value_array_clear ()
gboolean | camel_name_value_array_equal ()

## Types and Values

| CamelNameValueArray

## Object Hierarchy

        GBoxed
        ╰── CamelNameValueArray

## Description

## Functions

### camel_name_value_array_new ()

    CamelNameValueArray *
    camel_name_value_array_new (void);

Creates a new CamelNameValueArray. The returned pointer should be freed with `camel_name_value_array_free()` when no longer needed.

#### Returns

A new CamelNameValueArray.

See: camel_name_value_array_new_sized, camel_name_value_array_copy.

[transfer full]

Since: 3.24

### camel_name_value_array_new_sized ()

    CamelNameValueArray *
    camel_name_value_array_new_sized (guint reserve_size);

Creates a new CamelNameValueArray, which has reserved `reserve_size` elements. This value doesn't influence the `camel_name_value_array_get_length()`, which returns zero on the array returned from this function. The returned pointer should be freed with `camel_name_value_array_free()` when no longer needed.

#### Parameters

reserve_size | an array size to reserve |

#### Returns

A new CamelNameValueArray.

See: camel_name_value_array_new, camel_name_value_array_copy.

[transfer full]

Since: 3.24

### camel_name_value_array_copy ()

    CamelNameValueArray *
    camel_name_value_array_copy (const CamelNameValueArray *array);

Creates a new copy of the `array` . The returned pointer should be freed with `camel_name_value_array_free()` when no longer needed.

#### Parameters

array | a CamelNameValueArray. | [nullable]

#### Returns

A new copy of the `array` .

See: camel_name_value_array_new, camel_name_value_array_new_sized.

[transfer full]

Since: 3.24

### camel_name_value_array_free ()

    void
    camel_name_value_array_free (CamelNameValueArray *array);

Frees the `array` , previously allocated by `camel_name_value_array_new()`, `camel_name_value_array_new_sized()` or `camel_name_value_array_copy()`. If the `array` is `NULL`, then does nothing.

#### Parameters

array | a CamelNameValueArray, or `NULL`. | [nullable]

Since: 3.24

### camel_name_value_array_get_length ()

    guint
    camel_name_value_array_get_length (const CamelNameValueArray *array);

#### Parameters

array | a CamelNameValueArray. | [nullable]

#### Returns

Length of the `array` , aka how many elements are stored in the `array` .

Since: 3.24

### camel_name_value_array_get ()

    gboolean
    camel_name_value_array_get (const CamelNameValueArray *array,
                                guint index,
                                const gchar **out_name,
                                const gchar **out_value);

Returns the name and the value of the element at index `index` . Either of the `out_name` and `out_value` can be `NULL`, to not return that part.

#### Parameters

array | a CamelNameValueArray |
index | an index |
out_name | A place to store the name of the element, or `NULL`. | [out][nullable]
out_value | A place to store the value of the element, or `NULL`. | [out][nullable]

#### Returns

`TRUE` on success, `FALSE` otherwise.

See: camel_name_value_array_get_name, camel_name_value_array_get_value, camel_name_value_array_get_named

Since: 3.24

### camel_name_value_array_get_named ()

    const gchar *
    camel_name_value_array_get_named (const CamelNameValueArray *array,
                                      CamelCompareType compare_type,
                                      const gchar *name);

Returns the value of the first element named `name` , or `NULL` when there is no element of such `name` in the `array` . The `compare_type` determines how to compare the names.

#### Parameters

array | a CamelNameValueArray |
compare_type | a compare type, one of CamelCompareType |
name | a name |

#### Returns

Value of the first element named `name` , or `NULL`.

See: camel_name_value_array_get, camel_name_value_array_get_name.

[transfer none][nullable]

Since: 3.24

### camel_name_value_array_get_name ()

    const gchar *
    camel_name_value_array_get_name (const CamelNameValueArray *array,
                                     guint index);

Returns the name of the element at index `index` .

#### Parameters

array | a CamelNameValueArray |
index | an index |

#### Returns

Name of the element at the given `index` , or `NULL` on error.

See: camel_name_value_array_get, camel_name_value_array_get_value.

[transfer none][nullable]

Since: 3.24

### camel_name_value_array_get_value ()

    const gchar *
    camel_name_value_array_get_value (const CamelNameValueArray *array,
                                      guint index);

Returns the value of the element at index `index` .

#### Parameters

array | a CamelNameValueArray |
index | an index |

#### Returns

Value of the element at the given `index` , or `NULL` on error.

See: camel_name_value_array_get, camel_name_value_array_get_name.

[transfer none][nullable]

Since: 3.24

### camel_name_value_array_append ()

    void
    camel_name_value_array_append (CamelNameValueArray *array,
                                   const gchar *name,
                                   const gchar *value);

Appends a new element of the name `name` and the value `value` at the end of `array` .

See: camel_name_value_array_set_named

#### Parameters

array | a CamelNameValueArray |
name | a name |
value | a value |

Since: 3.24

### camel_name_value_array_set ()

    gboolean
    camel_name_value_array_set (CamelNameValueArray *array,
                                guint index,
                                const gchar *name,
                                const gchar *value);

Sets both the `name` and the `value` of the element at index `index` .

#### Parameters

array | a CamelNameValueArray |
index | an index |
name | a name |
value | a value |

#### Returns

Whether the `array` changed.

See: camel_name_value_array_append, camel_name_value_array_set_name, camel_name_value_array_set_value

Since: 3.24

### camel_name_value_array_set_name ()

    gboolean
    camel_name_value_array_set_name (CamelNameValueArray *array,
                                     guint index,
                                     const gchar *name);

Sets the `name` of the element at index `index` .

#### Parameters

array | a CamelNameValueArray |
index | an index |
name | a name |

#### Returns

Whether the `array` changed.

See: camel_name_value_array_set, camel_name_value_array_set_value

Since: 3.24

### camel_name_value_array_set_value ()

    gboolean
    camel_name_value_array_set_value (CamelNameValueArray *array,
                                      guint index,
                                      const gchar *value);

Sets the `value` of the element at index `index` .

#### Parameters

array | a CamelNameValueArray |
index | an index |
value | a value |

#### Returns

Whether the `array` changed.

See: camel_name_value_array_set, camel_name_value_array_set_name

Since: 3.24

### camel_name_value_array_set_named ()

    gboolean
    camel_name_value_array_set_named (CamelNameValueArray *array,
                                      CamelCompareType compare_type,
                                      const gchar *name,
                                      const gchar *value);

Finds an element named `name` and sets its value to `value` , or appends a new element, in case no such named element exists in the `array` yet. In case there are more elements named with `name` only the first occurrence is changed. The `compare_type` determines how to compare the names.

#### Parameters

array | a CamelNameValueArray |
compare_type | a compare type, one of CamelCompareType |
name | a name |
value | a value |

#### Returns

Whether the `array` changed.

See: camel_name_value_array_append, camel_name_value_array_set

Since: 3.24

### camel_name_value_array_remove ()

    gboolean
    camel_name_value_array_remove (CamelNameValueArray *array,
                                   guint index);

Removes element at index `index` .

#### Parameters

array | a CamelNameValueArray |
index | an index to remove |

#### Returns

Whether the element was removed.

Since: 3.24

### camel_name_value_array_remove_named ()

    guint
    camel_name_value_array_remove_named (CamelNameValueArray *array,
                                         CamelCompareType compare_type,
                                         const gchar *name,
                                         gboolean all_occurrences);

Removes elements of the `array` with the given `name` . The `compare_type` determines hot to compare the names. If the `all_occurrences` is set to `TRUE`, then every elements with the `name` are removed, otherwise only the first occurrence is removed.

#### Parameters

array | a CamelNameValueArray |
compare_type | a compare type, one of CamelCompareType |
name | a name to remove |
all_occurrences | whether to remove all occurrences of the `name` |

#### Returns

How many elements had been removed.

Since: 3.24

### camel_name_value_array_clear ()

    void
    camel_name_value_array_clear (CamelNameValueArray *array);

Removes all elements of the `array` .

#### Parameters

array | a CamelNameValueArray |

Since: 3.24

### camel_name_value_array_equal ()

    gboolean
    camel_name_value_array_equal (const CamelNameValueArray *array_a,
                                  const CamelNameValueArray *array_b,
                                  CamelCompareType compare_type);

Compares content of the two CamelNameValueArray and returns whether they equal. Note this is an expensive operation for large arrays.

#### Parameters

array_a | the first CamelNameValueArray. | [nullable]
array_b | the second CamelNameValueArray. | [nullable]
compare_type | a compare type, one of CamelCompareType |

#### Returns

Whether the two CamelNameValueArray have the same content.

Since: 3.24

## Types and Values

### CamelNameValueArray

    typedef struct _CamelNameValueArray CamelNameValueArray;

Since: 3.24