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_tablelh_table_new (int size, lh_entry_free_fn *free_fn, lh_hash_fn *hash_fn, lh_equal_fn *equal_fn)
 
struct lh_tablelh_kchar_table_new (int size, lh_entry_free_fn *free_fn)
 
struct lh_tablelh_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_entrylh_table_lookup_entry (struct lh_table *t, const void *k)
 
struct lh_entrylh_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
tablea struct lh_table * to iterate over
entrya struct lh_entry * variable to hold each element
tmpa 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
msgMessage 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
sizeinitial table size.
free_fncallback 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
sizeinitial table size.
free_fncallback 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
tthe table to delete from.
ka 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
tthe table to delete from.
ea 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
ttable 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
tthe table to insert into.
ka pointer to the key to insert.
va 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
tthe table to insert into.
ka pointer to the key to insert.
va pointer to the value to insert.
hhash value of the key to insert
optsif 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
tthe table to lookup
ka 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
tthe table to lookup
ka 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
tthe table to lookup
ka pointer to the key to lookup
hhash 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
tthe table to lookup
ka pointer to the key to lookup
va 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
sizeinitial table size. The table is automatically resized although this incurs a performance penalty.
free_fncallback 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_fnfunction 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_fncomparison 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
tPointer to table to resize.
new_sizeNew table size. Must be positive.
Returns
On success, 0 is returned. On error, a negative value is returned.