Quark list: GNOME Data Access 5 manual

## Quark list Quark list — Manages lists of KEY=VALUE pairs |

## Stability Level

Stable, unless otherwise indicated

## Functions

GdaQuarkList * | gda_quark_list_new ()
GdaQuarkList * | gda_quark_list_new_from_string ()
GdaQuarkList * | gda_quark_list_copy ()
void | gda_quark_list_free ()
void | gda_quark_list_clear ()
void | gda_quark_list_add_from_string ()
const gchar * | gda_quark_list_find ()
void | gda_quark_list_protect_values ()
void | gda_quark_list_remove ()
void | gda_quark_list_foreach ()

## Types and Values

| GdaQuarkList

## Object Hierarchy

        GBoxed
        ╰── GdaQuarkList

## Description

This object is used to store KEY=VALUE pairs. It is mainly used internally by Libgda to store connection parameters.

Authentification values are kept in a mangled form in memory, and unmangled when they are requested using `gda_quark_list_find()`, and when you don't need them anymore, call `gda_quark_list_protect_values()` to remove the unmangled version.

## Functions

### gda_quark_list_new ()

    GdaQuarkList *
    gda_quark_list_new (void);

Creates a new GdaQuarkList, which is a set of key->value pairs, very similar to GLib's GHashTable, but with the only purpose to make easier the parsing and creation of data source connection strings.

#### Returns

the newly created GdaQuarkList.

Free-function: gda_quark_list_free.

[transfer full]

### gda_quark_list_new_from_string ()

    GdaQuarkList *
    gda_quark_list_new_from_string (const gchar *string);

Creates a new GdaQuarkList given a string.

`string` must be a semi-colon separated list of "<key>=<value>" strings (for example "DB_NAME=notes;USERNAME=alfred"). Each key and value must respect the RFC 1738 recommendations: the

`<>"#%{}|\^~[]'`;/?:@=&` and space characters are replaced by `"%`ab`"` where `ab` is the hexadecimal number corresponding to the character (for example the

"DB_NAME=notes;USERNAME=al%`20fred`" string will specify a username as "al fred"). If this formalism is not respected, then some unexpected results may occur.

#### Parameters

string | a string. |

#### Returns

the newly created GdaQuarkList.

Free-function: gda_quark_list_free.

[transfer full]

### gda_quark_list_copy ()

    GdaQuarkList *
    gda_quark_list_copy (GdaQuarkList *qlist);

Creates a new GdaQuarkList from an existing one.

#### Parameters

qlist | quark_list to get a copy from. |

#### Returns

a newly allocated GdaQuarkList with a copy of the data in `qlist` .

### gda_quark_list_free ()

    void
    gda_quark_list_free (GdaQuarkList *qlist);

Releases all memory occupied by the given GdaQuarkList.

#### Parameters

qlist | a GdaQuarkList. |

### gda_quark_list_clear ()

    void
    gda_quark_list_clear (GdaQuarkList *qlist);

Removes all strings in the given GdaQuarkList.

#### Parameters

qlist | a GdaQuarkList. |

### gda_quark_list_add_from_string ()

    void
    gda_quark_list_add_from_string (GdaQuarkList *qlist,
                                    const gchar *string,
                                    gboolean cleanup);

`string` must be a semi-colon separated list of "<key>=<value>" strings (for example "DB_NAME=notes;USERNAME=alfred"). Each key and value must respect the RFC 1738 recommendations: the

`<>"#%{}|\^~[]'`;/?:@=&` and space characters are replaced by `"%`ab`"` where `ab` is the hexadecimal number corresponding to the character (for example the

"DB_NAME=notes;USERNAME=al%`20fred`" string will specify a username as "al fred"). If this formalism is not respected, then some unexpected results may occur.

Adds new key->value pairs from the given `string` . If `cleanup` is set to `TRUE`, the previous contents will be discarded before adding the new pairs.

#### Parameters

qlist | a GdaQuarkList. |
string | a string. |
cleanup | whether to cleanup the previous content or not. |

### gda_quark_list_find ()

    const gchar *
    gda_quark_list_find (GdaQuarkList *qlist,
                         const gchar *name);

Searches for the value identified by `name` in the given GdaQuarkList. For protected values (authentification data), don't forget to call `gda_quark_list_protect_values()` when you don't need them anymore (when needed again, they will be unmangled again).

#### Parameters

qlist | a GdaQuarkList. |
name | the name of the value to search for. |

#### Returns

the value associated with the given key if found, or `NULL` if not found.

### gda_quark_list_protect_values ()

    void
    gda_quark_list_protect_values (GdaQuarkList *qlist);

Call this function to get rid of the clear version of the value associated to `name` .

#### Parameters

qlist | a GdaQuarkList |

Since: 5.2.0

### gda_quark_list_remove ()

    void
    gda_quark_list_remove (GdaQuarkList *qlist,
                           const gchar *name);

Removes an entry from the GdaQuarkList, given its name.

#### Parameters

qlist | a GdaQuarkList structure. |
name | an entry name. |

### gda_quark_list_foreach ()

    void
    gda_quark_list_foreach (GdaQuarkList *qlist,
                            GHFunc func,
                            gpointer user_data);

Calls the given function for each of the key/value pairs in `qlist` . The function is passed the key and value of each pair, and the given user_data parameter. `qlist` may not be modified while iterating over it.

#### Parameters

qlist | a GdaQuarkList structure. |
func | the function to call for each key/value pair. | [scope call]
user_data | user data to pass to the function. | [closure]

## Types and Values

### GdaQuarkList

    typedef struct _GdaQuarkList GdaQuarkList;