json-c 0.13

Data Structures | Macros | Typedefs | Functions
linkhash.h File Reference

Internal methods for working with json_type_object objects. Although this is exposed by the json_object_get_object() function and within the json_object_iter type, it is not recommended for direct use. More...

## Data Structures
struct | lh_entry
struct | lh_table

## Macros
#define | LH_PRIME 0x9e370001UL
#define | LH_LOAD_FACTOR 0.66
#define | LH_EMPTY (void*)-1
#define | LH_FREED (void*)-2
#define | JSON_C_STR_HASH_DFLT 0
#define | JSON_C_STR_HASH_PERLLIKE 1
#define | lh_foreach(table, entry) for(entry = table->head; entry; entry = entry->next)
#define | lh_foreach_safe(table, entry, tmp) for(entry = table->head; entry && ((tmp = entry->next) || 1); entry = tmp)
#define | _LH_INLINE inline
#define | _LH_UNCONST(a) ((void *)(uintptr_t)(const void *)(a))
#define | lh_entry_k(entry) _LH_UNCONST((entry)->k)
#define | lh_entry_v(entry) _LH_UNCONST((entry)->v)

## Typedefs
typedef void() | lh_entry_free_fn(struct lh_entry *e)
typedef unsigned long() | lh_hash_fn(const void *k)
typedef int() | lh_equal_fn(const void *k1, const void *k2)
typedef struct lh_table | lh_table

## Functions
int | json_global_set_string_hash (const int h)
struct lh_table * | lh_table_new (int size, lh_entry_free_fn *free_fn, lh_hash_fn *hash_fn, lh_equal_fn *equal_fn)
struct lh_table * | lh_kchar_table_new (int size, lh_entry_free_fn *free_fn)
struct lh_table * | lh_kptr_table_new (int size, lh_entry_free_fn *free_fn)
void | lh_table_free (struct lh_table *t)
int | lh_table_insert (struct lh_table *t, const void *k, const void *v)
int | lh_table_insert_w_hash (struct lh_table *t, const void *k, const void *v, const unsigned long h, const unsigned opts)
struct lh_entry * | lh_table_lookup_entry (struct lh_table *t, const void *k)
struct lh_entry * | lh_table_lookup_entry_w_hash (struct lh_table *t, const void *k, const unsigned long h)
const void * | lh_table_lookup (struct lh_table *t, const void *k)
json_bool | lh_table_lookup_ex (struct lh_table *t, const void *k, void **v)
int | lh_table_delete_entry (struct lh_table *t, struct lh_entry *e)
int | lh_table_delete (struct lh_table *t, const void *k)
int | lh_table_length (struct lh_table *t)
void | lh_abort (const char *msg,...)
int | lh_table_resize (struct lh_table *t, int new_size)

## Detailed Description

Internal methods for working with json_type_object objects. Although this is exposed by the json_object_get_object() function and within the json_object_iter type, it is not recommended for direct use.

## Macro Definition Documentation

## ◆ _LH_INLINE

#define _LH_INLINE inline

Deprecated:
  Don't use this outside of linkhash.h:

## ◆ _LH_UNCONST

#define _LH_UNCONST | ( |  | a | ) | ((void *)(uintptr_t)(const void *)(a))

Deprecated:
  Don't use this outside of linkhash.h:

## ◆ JSON_C_STR_HASH_DFLT

#define JSON_C_STR_HASH_DFLT 0

default string hash function

## ◆ JSON_C_STR_HASH_PERLLIKE

#define JSON_C_STR_HASH_PERLLIKE 1

perl-like string hash function

## ◆ LH_EMPTY

#define LH_EMPTY (void*)-1

sentinel pointer value for empty slots

## ◆ lh_entry_k

#define lh_entry_k | ( |  | entry | ) | _LH_UNCONST((entry)->k)

Return a non-const version of lh_entry.k.

lh_entry.k is const to indicate and help ensure that linkhash itself doesn't modify it, but callers are allowed to do what they want with it. See also lh_entry.k_is_constant

## ◆ lh_entry_v

#define lh_entry_v | ( |  | entry | ) | _LH_UNCONST((entry)->v)

Return a non-const version of lh_entry.v.

v is const to indicate and help ensure that linkhash itself doesn't modify it, but callers are allowed to do what they want with it.

## ◆ lh_foreach

#define lh_foreach | ( |  | table,
|  |  | entry
| ) |  | for(entry = table->head; entry; entry = entry->next)

Convenience list iterator.

## ◆ lh_foreach_safe

#define lh_foreach_safe | ( |  | table,
|  |  | entry,
|  |  | tmp
| ) |  | for(entry = table->head; entry && ((tmp = entry->next) || 1); entry = tmp)

lh_foreach_safe allows calling of deletion routine while iterating.

Parameters

  table | a struct lh_table * to iterate over
  entry | a struct lh_entry * variable to hold each element
  tmp | a struct lh_entry * variable to hold a temporary pointer to the next element

## ◆ LH_FREED

#define LH_FREED (void*)-2

sentinel pointer value for freed slots

## ◆ LH_LOAD_FACTOR

#define LH_LOAD_FACTOR 0.66

The fraction of filled hash buckets until an insert will cause the table to be resized. This can range from just above 0 up to 1.0.

## ◆ LH_PRIME

#define LH_PRIME 0x9e370001UL

golden prime used in hash functions

## Typedef Documentation

## ◆ lh_entry_free_fn

typedef void() lh_entry_free_fn(struct lh_entry *e)

callback function prototypes

## ◆ lh_equal_fn

typedef int() lh_equal_fn(const void *k1, const void *k2)

callback function prototypes

## ◆ lh_hash_fn

typedef unsigned long() lh_hash_fn(const void *k)

callback function prototypes

## ◆ lh_table

typedef struct lh_table lh_table

## Function Documentation

## ◆ json_global_set_string_hash()

int json_global_set_string_hash | ( | const int | h | ) |

This function sets the hash function to be used for strings. Must be one of the JSON_C_STR_HASH_* values.

Returns
  0 - ok, -1 if parameter was invalid

## ◆ lh_abort()

void lh_abort | ( | const char * | msg,
|  |  | ...
| ) |  |

Prints a message to `stdout`, then exits the program with an exit code of `1`.

Parameters

  msg | Message format string, like for `printf`.
  ... | Format args.

Deprecated:
  Since it is not a good idea to exit the entire program because of an internal library failure, json-c will no longer use this function internally. However, because its interface is public, it will remain part of the API on the off chance of legacy software using it externally.

## ◆ lh_kchar_table_new()

struct lh_table* lh_kchar_table_new | ( | int | size,
|  | lh_entry_free_fn * | free_fn
| ) |  |

Convenience function to create a new linkhash table with char keys.

Parameters

  size | initial table size.
  free_fn | callback function used to free memory for entries.

Returns
  On success, a pointer to the new linkhash table is returned. On error, a null pointer is returned.

## ◆ lh_kptr_table_new()

struct lh_table* lh_kptr_table_new | ( | int | size,
|  | lh_entry_free_fn * | free_fn
| ) |  |

Convenience function to create a new linkhash table with ptr keys.

Parameters

  size | initial table size.
  free_fn | callback function used to free memory for entries.

Returns
  On success, a pointer to the new linkhash table is returned. On error, a null pointer is returned.

## ◆ lh_table_delete()

int lh_table_delete | ( | struct lh_table * | t,
|  | const void * | k
| ) |  |

Delete a record from the table.

If a callback free function is provided then it is called for the for the item being deleted.

Parameters

  t | the table to delete from.
  k | a pointer to the key to delete.

Returns
  0 if the item was deleted.
  -1 if it was not found.

## ◆ lh_table_delete_entry()

int lh_table_delete_entry | ( | struct lh_table * | t,
|  | struct lh_entry * | e
| ) |  |

Delete a record from the table.

If a callback free function is provided then it is called for the for the item being deleted.

Parameters

  t | the table to delete from.
  e | a pointer to the entry to delete.

Returns
  0 if the item was deleted.
  -1 if it was not found.

## ◆ lh_table_free()

void lh_table_free | ( | struct lh_table * | t | ) |

Free a linkhash table.

If a lh_entry_free_fn callback free function was provided then it is called for all entries in the table.

Parameters

  t | table to free.

## ◆ lh_table_insert()

int lh_table_insert | ( | struct lh_table * | t,
|  | const void * | k,
|  | const void * | v
| ) |  |

Insert a record into the table.

Parameters

  t | the table to insert into.
  k | a pointer to the key to insert.
  v | a pointer to the value to insert.

Returns
  On success, `0` is returned. On error, a negative value is returned.

## ◆ lh_table_insert_w_hash()

int lh_table_insert_w_hash | ( | struct lh_table * | t,
|  | const void * | k,
|  | const void * | v,
|  | const unsigned long | h,
|  | const unsigned | opts
| ) |  |

Insert a record into the table using a precalculated key hash.

The hash h, which should be calculated with lh_get_hash() on k, is provided by the caller, to allow for optimization when multiple operations with the same key are known to be needed.

Parameters

  t | the table to insert into.
  k | a pointer to the key to insert.
  v | a pointer to the value to insert.
  h | hash value of the key to insert
  opts | if set to JSON_C_OBJECT_KEY_IS_CONSTANT, sets lh_entry.k_is_constant so t's free function knows to avoid freeing the key.

## ◆ lh_table_length()

int lh_table_length | ( | struct lh_table * | t | ) |

## ◆ lh_table_lookup()

const void* lh_table_lookup | ( | struct lh_table * | t,
|  | const void * | k
| ) |  |

Lookup a record into the table.

Parameters

  t | the table to lookup
  k | a pointer to the key to lookup

Returns
  a pointer to the found value or NULL if it does not exist.

Deprecated:
  Use lh_table_lookup_ex() instead.

## ◆ lh_table_lookup_entry()

struct lh_entry* lh_table_lookup_entry | ( | struct lh_table * | t,
|  | const void * | k
| ) |  |

Lookup a record in the table.

Parameters

  t | the table to lookup
  k | a pointer to the key to lookup

Returns
  a pointer to the record structure of the value or NULL if it does not exist.

## ◆ lh_table_lookup_entry_w_hash()

struct lh_entry* lh_table_lookup_entry_w_hash | ( | struct lh_table * | t,
|  | const void * | k,
|  | const unsigned long | h
| ) |  |

Lookup a record in the table using a precalculated key hash.

The hash h, which should be calculated with lh_get_hash() on k, is provided by the caller, to allow for optimization when multiple operations with the same key are known to be needed.

Parameters

  t | the table to lookup
  k | a pointer to the key to lookup
  h | hash value of the key to lookup

Returns
  a pointer to the record structure of the value or NULL if it does not exist.

## ◆ lh_table_lookup_ex()

json_bool lh_table_lookup_ex | ( | struct lh_table * | t,
|  | const void * | k,
|  | void ** | v
| ) |  |

Lookup a record in the table.

Parameters

  t | the table to lookup
  k | a pointer to the key to lookup
  v | a pointer to a where to store the found value (set to NULL if it doesn't exist).

Returns
  whether or not the key was found

## ◆ lh_table_new()

struct lh_table* lh_table_new | ( | int | size,
|  | lh_entry_free_fn * | free_fn,
|  | lh_hash_fn * | hash_fn,
|  | lh_equal_fn * | equal_fn
| ) |  |

Create a new linkhash table.

Parameters

  size | initial table size. The table is automatically resized although this incurs a performance penalty.
  free_fn | callback function used to free memory for entries when lh_table_free or lh_table_delete is called. If NULL is provided, then memory for keys and values must be freed by the caller.
  hash_fn | function used to hash keys. 2 standard ones are defined: lh_ptr_hash and lh_char_hash for hashing pointer values and C strings respectively.
  equal_fn | comparison function to compare keys. 2 standard ones defined: lh_ptr_hash and lh_char_hash for comparing pointer values and C strings respectively.

Returns
  On success, a pointer to the new linkhash table is returned. On error, a null pointer is returned.

## ◆ lh_table_resize()

int lh_table_resize | ( | struct lh_table * | t,
|  | int | new_size
| ) |  |

Resizes the specified table.

Parameters

  t | Pointer to table to resize.
  new_size | New table size. Must be positive.

Returns
  On success, `0` is returned. On error, a negative value is returned.