Loading...
Searching...
No Matches
Dictionary

Simple hash table API (string keys). More...

## Typedefs

typedef void(* | ec_dict_elt_free_t) (void *)
| Callback function for freeing dictionary elements.

## Functions

struct ec_dict * | ec_dict (void)
| Create a hash table.
void * | ec_dict_get (const struct ec_dict *dict, const char *key)
| Get a value from the hash table.
bool | ec_dict_has_key (const struct ec_dict *dict, const char *key)
| Check if the hash table contains this key.
int | ec_dict_del (struct ec_dict *dict, const char *key)
| Delete an object from the hash table.
int | ec_dict_set (struct ec_dict *dict, const char *key, void *val, ec_dict_elt_free_t free_cb)
| Add/replace an object in the hash table.
void | ec_dict_free (struct ec_dict *dict)
| Free a hash table and all its objects.
size_t | ec_dict_len (const struct ec_dict *dict)
| Get the length of a hash table.
struct ec_dict * | ec_dict_dup (const struct ec_dict *dict)
| Duplicate a hash table.
void | ec_dict_dump (FILE *out, const struct ec_dict *dict)
| Dump a hash table.
struct ec_dict_elt_ref * | ec_dict_iter (const struct ec_dict *dict)
| Iterate the elements in the hash table.
struct ec_dict_elt_ref * | ec_dict_iter_next (struct ec_dict_elt_ref *iter)
| Make the iterator point to the next element in the hash table.
const char * | ec_dict_iter_get_key (const struct ec_dict_elt_ref *iter)
| Get a pointer to the key of the current element.
void * | ec_dict_iter_get_val (const struct ec_dict_elt_ref *iter)
| Get the value of the current element.

## Detailed Description

Simple hash table API (string keys).

This file provides functions to store objects in hash tables, using strings as keys.

## Typedef Documentation

## ec_dict_elt_free_t

typedef void(* ec_dict_elt_free_t) (void *)

Callback function for freeing dictionary elements.

Definition at line 21 of file dict.h.

## Function Documentation

## ec_dict()

struct ec_dict * ec_dict | ( | void |  | ) |

Create a hash table.

Returns
  The hash table, or NULL on error (errno is set).

## ec_dict_get()

void * ec_dict_get | ( | const struct ec_dict * | dict,
|  | const char * | key )

Get a value from the hash table.

Parameters

  dict | The hash table.
  key | The key string. Must not be NULL.

Returns
  The element if it is found, or NULL on error (errno is set). In case of success but the element is NULL, errno is set to 0. If key is NULL, errno is set to EINVAL.

Examples
  readline/main.c.

## ec_dict_has_key()

bool ec_dict_has_key | ( | const struct ec_dict * | dict,
|  | const char * | key )

Check if the hash table contains this key.

Parameters

  dict | The hash table.
  key | The key string. Must not be NULL.

Returns
  true if it contains the key, false otherwise. If key is NULL, false is returned and errno is set to EINVAL.

## ec_dict_del()

int ec_dict_del | ( | struct ec_dict * | dict,
|  | const char * | key )

Delete an object from the hash table.

Parameters

  dict | The hash table.
  key | The key string. Must not be NULL.

Returns
  0 on success, or -1 on error (errno is set).

## ec_dict_set()

int ec_dict_set | ( | struct ec_dict * | dict,
|  | const char * | key,
|  | void * | val,
|  | ec_dict_elt_free_t | free_cb )

Add/replace an object in the hash table.

Parameters

  dict | The hash table.
  key | The key string. Must not be NULL.
  val | The pointer to be saved in the hash table.
  free_cb | An optional pointer to a destructor function called when an object is destroyed (ec_dict_del() or ec_dict_free()).

Returns
  0 on success, or -1 on error (errno is set). On error, the passed value is freed (free_cb(val) is called).

Examples
  readline/main.c.

## ec_dict_free()

void ec_dict_free | ( | struct ec_dict * | dict | ) |

Free a hash table and all its objects.

Parameters

  dict | The hash table.

## ec_dict_len()

size_t ec_dict_len | ( | const struct ec_dict * | dict | ) |

Get the length of a hash table.

Parameters

  dict | The hash table.

Returns
  The length of the hash table.

## ec_dict_dup()

struct ec_dict * ec_dict_dup | ( | const struct ec_dict * | dict | ) |

Duplicate a hash table.

A reference counter is shared between the clones of hash tables so that the objects are freed only when the last reference is destroyed.

Parameters

  dict | The hash table.

Returns
  The duplicated hash table, or NULL on error (errno is set).

## ec_dict_dump()

void ec_dict_dump | ( | FILE * | out,
|  | const struct ec_dict * | dict )

Dump a hash table.

Parameters

  out | The stream where the dump is sent.
  dict | The hash table.

## ec_dict_iter()

struct ec_dict_elt_ref * ec_dict_iter | ( | const struct ec_dict * | dict | ) |

Iterate the elements in the hash table.

The typical usage is as below:

for (iter = ec_dict_iter(dict);
iter != NULL;
iter = ec_dict_iter_next(iter)) {
printf(" %s: %p\n",
ec_dict_iter_get_key(iter),
ec_dict_iter_get_val(iter));
}
ec_dict_iter_get_val
void * ec_dict_iter_get_val(const struct ec_dict_elt_ref *iter)
Get the value of the current element.
ec_dict_iter_next
struct ec_dict_elt_ref * ec_dict_iter_next(struct ec_dict_elt_ref *iter)
Make the iterator point to the next element in the hash table.
ec_dict_iter_get_key
const char * ec_dict_iter_get_key(const struct ec_dict_elt_ref *iter)
Get a pointer to the key of the current element.
ec_dict_iter
struct ec_dict_elt_ref * ec_dict_iter(const struct ec_dict *dict)
Iterate the elements in the hash table.

Parameters

  dict | The hash table.

Returns
  An iterator element, or NULL if the dict is empty.

## ec_dict_iter_next()

struct ec_dict_elt_ref * ec_dict_iter_next | ( | struct ec_dict_elt_ref * | iter | ) |

Make the iterator point to the next element in the hash table.

Parameters

  iter | The hash table iterator.

Returns
  An iterator element, or NULL if there is no more element.

## ec_dict_iter_get_key()

const char * ec_dict_iter_get_key | ( | const struct ec_dict_elt_ref * | iter | ) |

Get a pointer to the key of the current element.

Parameters

  iter | The hash table iterator.

Returns
  The current element key, or NULL if the iterator points to an invalid element.

## ec_dict_iter_get_val()

void * ec_dict_iter_get_val | ( | const struct ec_dict_elt_ref * | iter | ) |

Get the value of the current element.

Parameters

  iter | The hash table iterator.

Returns
  The current element value, or NULL if the iterator points to an invalid element.