Main Page | Modules | Alphabetical List | Data Structures | File List | Data Fields | Globals | Related Pages

KVP: Key-Value Pairs
[Query Object Framework]


Detailed Description

A KvpFrame is a set of associations between character strings (keys) and KvpValue structures. A KvpValue is a union with possible types enumerated in the KvpValueType enum, and includes, among other things, ints, doubles, strings, guid's, lists, time and numeric values. KvpValues may also be other frames, so KVP is inherently heirarchical.

Values are stored in a 'slot' associated with a key. Pointers passed as arguments into set_slot and get_slot are the responsibility of the caller. Pointers returned by get_slot are owned by the kvp_frame. Make copies as needed.

A 'path' is a sequence of keys that can be followed to a value. Paths may be specified as varargs (variable number of arguments to a subrutine, NULL-terminated), as a GSList, or as a standard URL-like path name. The later is parsed and treated in the same way as file paths would be: / separates keys, /./ is treated as / and /../ means backup one level. Repeated slashes are treated as one slash.

Note that although, in principle, keys may contain the / and . and .. characters, doing so may lead to confusion, and will make path-string parsing routines fail. In other words, don't use a key such as 'some/key' or 'some/./other/../key' because you may get unexpected results.

To set a value into a frame, you will want to use one of the kvp_frame_set_xxx() routines. Most of the other routines provide only low-level access that you probably shouldn't use.


Files

file  kvp-util.h
 GnuCash KVP utility functions.

file  kvp_frame.h
 A key-value frame system.


Modules

group KVP_Private

Data Structures

struct  GHashTableKVPair

Hash Utilities

GSList * g_hash_table_key_value_pairs (GHashTable *table)
void g_hash_table_kv_pair_free_gfunc (gpointer data, gpointer user_data)

KvpFrame Constructors

KvpFramekvp_frame_new (void)
void kvp_frame_delete (KvpFrame *frame)
KvpFramekvp_frame_copy (const KvpFrame *frame)
gboolean kvp_frame_is_empty (KvpFrame *frame)

KvpFrame Basic Value Storing

void kvp_frame_set_gint64 (KvpFrame *frame, const char *path, gint64 ival)
void kvp_frame_set_double (KvpFrame *frame, const char *path, double dval)
void kvp_frame_set_gnc_numeric (KvpFrame *frame, const char *path, gnc_numeric nval)
void kvp_frame_set_timespec (KvpFrame *frame, const char *path, Timespec ts)
void kvp_frame_set_str (KvpFrame *frame, const char *path, const char *str)
void kvp_frame_set_guid (KvpFrame *frame, const char *path, const GUID *guid)
void kvp_frame_set_frame (KvpFrame *frame, const char *path, KvpFrame *chld)
void kvp_frame_set_frame_nc (KvpFrame *frame, const char *path, KvpFrame *chld)
KvpFramekvp_frame_set_value (KvpFrame *frame, const char *path, const KvpValue *value)
KvpFramekvp_frame_set_value_nc (KvpFrame *frame, const char *path, KvpValue *value)
KvpValuekvp_frame_replace_value_nc (KvpFrame *frame, const char *slot, KvpValue *new_value)

KvpFrame URL handling

void kvp_frame_add_url_encoding (KvpFrame *frame, const char *enc)

KvpFrame Glist Bag Storing

void kvp_frame_add_gint64 (KvpFrame *frame, const char *path, gint64 ival)
void kvp_frame_add_double (KvpFrame *frame, const char *path, double dval)
void kvp_frame_add_gnc_numeric (KvpFrame *frame, const char *path, gnc_numeric nval)
void kvp_frame_add_timespec (KvpFrame *frame, const char *path, Timespec ts)
void kvp_frame_add_str (KvpFrame *frame, const char *path, const char *str)
void kvp_frame_add_guid (KvpFrame *frame, const char *path, const GUID *guid)
void kvp_frame_add_frame (KvpFrame *frame, const char *path, KvpFrame *chld)
void kvp_frame_add_frame_nc (KvpFrame *frame, const char *path, KvpFrame *chld)
KvpFramekvp_frame_add_value (KvpFrame *frame, const char *path, KvpValue *value)
KvpFramekvp_frame_add_value_nc (KvpFrame *frame, const char *path, KvpValue *value)

KvpFrame Value Fetching

gint64 kvp_frame_get_gint64 (const KvpFrame *frame, const char *path)
double kvp_frame_get_double (const KvpFrame *frame, const char *path)
gnc_numeric kvp_frame_get_numeric (const KvpFrame *frame, const char *path)
char * kvp_frame_get_string (const KvpFrame *frame, const char *path)
GUIDkvp_frame_get_guid (const KvpFrame *frame, const char *path)
void * kvp_frame_get_binary (const KvpFrame *frame, const char *path, guint64 *size_return)
Timespec kvp_frame_get_timespec (const KvpFrame *frame, const char *path)
KvpValuekvp_frame_get_value (const KvpFrame *frame, const char *path)
KvpFramekvp_frame_get_frame (const KvpFrame *frame, const char *path)
KvpFramekvp_frame_get_frame_path (KvpFrame *frame, const char *,...)
KvpFramekvp_frame_get_frame_gslist (KvpFrame *frame, GSList *key_path)
KvpFramekvp_frame_get_frame_slash (KvpFrame *frame, const char *path)

KvpFrame KvpValue low-level storing routines.

KvpValuekvp_frame_replace_slot_nc (KvpFrame *frame, const char *slot, KvpValue *new_value)
void kvp_frame_set_slot (KvpFrame *frame, const char *key, const KvpValue *value)
void kvp_frame_set_slot_nc (KvpFrame *frame, const char *key, KvpValue *value)
void kvp_frame_set_slot_path (KvpFrame *frame, const KvpValue *value, const char *first_key,...)
void kvp_frame_set_slot_path_gslist (KvpFrame *frame, const KvpValue *value, GSList *key_path)

KvpFrame KvpValue Low-Level Retrieval Routines

KvpValuekvp_frame_get_slot (const KvpFrame *frame, const char *key)
KvpValuekvp_frame_get_slot_path (KvpFrame *frame, const char *first_key,...)
KvpValuekvp_frame_get_slot_path_gslist (KvpFrame *frame, GSList *key_path)
gint kvp_frame_compare (const KvpFrame *fa, const KvpFrame *fb)

KvpValue List Convenience Functions

gint kvp_glist_compare (const GList *list1, const GList *list2)
GList * kvp_glist_copy (const GList *list)
void kvp_glist_delete (GList *list)

KvpValue Constructors

KvpValuekvp_value_new_gint64 (gint64 value)
KvpValuekvp_value_new_double (double value)
KvpValuekvp_value_new_gnc_numeric (gnc_numeric value)
KvpValuekvp_value_new_string (const char *value)
KvpValuekvp_value_new_guid (const GUID *guid)
KvpValuekvp_value_new_timespec (Timespec timespec)
KvpValuekvp_value_new_binary (const void *data, guint64 datasize)
KvpValuekvp_value_new_frame (const KvpFrame *value)
KvpValuekvp_value_new_glist (const GList *value)
KvpValuekvp_value_new_binary_nc (void *data, guint64 datasize)
KvpValuekvp_value_new_glist_nc (GList *lst)
KvpValuekvp_value_new_frame_nc (KvpFrame *value)
void kvp_value_delete (KvpValue *value)
KvpValuekvp_value_copy (const KvpValue *value)
KvpFramekvp_value_replace_frame_nc (KvpValue *value, KvpFrame *newframe)
GList * kvp_value_replace_glist_nc (KvpValue *value, GList *newlist)

KvpValue Value access

KvpValueType kvp_value_get_type (const KvpValue *value)
gint64 kvp_value_get_gint64 (const KvpValue *value)
double kvp_value_get_double (const KvpValue *value)
gnc_numeric kvp_value_get_numeric (const KvpValue *value)
char * kvp_value_get_string (const KvpValue *value)
GUIDkvp_value_get_guid (const KvpValue *value)
void * kvp_value_get_binary (const KvpValue *value, guint64 *size_return)
GList * kvp_value_get_glist (const KvpValue *value)
KvpFramekvp_value_get_frame (const KvpValue *value)
Timespec kvp_value_get_timespec (const KvpValue *value)
gint kvp_value_compare (const KvpValue *va, const KvpValue *vb)

Iterators

void kvp_frame_for_each_slot (KvpFrame *f, void(*proc)(const char *key, KvpValue *value, gpointer data), gpointer data)

Defines

#define kvp_frame   KvpFrame
#define kvp_value   KvpValue
#define kvp_value_t   KvpValueType

Typedefs

typedef _KvpFrame KvpFrame
typedef _KvpValue KvpValue

Enumerations

enum  KvpValueType {
  KVP_TYPE_GINT64 = 1, KVP_TYPE_DOUBLE, KVP_TYPE_NUMERIC, KVP_TYPE_STRING,
  KVP_TYPE_GUID, KVP_TYPE_TIMESPEC, KVP_TYPE_BINARY, KVP_TYPE_GLIST,
  KVP_TYPE_FRAME
}

Functions

gint double_compare (double v1, double v2)
gchar * kvp_value_to_string (const KvpValue *val)
gboolean kvp_value_binary_append (KvpValue *v, void *data, guint64 size)
gchar * kvp_frame_to_string (const KvpFrame *frame)
gchar * binary_to_string (const void *data, guint32 size)
gchar * kvp_value_glist_to_string (const GList *list)
GHashTable * kvp_frame_get_hash (const KvpFrame *frame)


Typedef Documentation

typedef struct _KvpFrame KvpFrame
 

Opaque frame structure

typedef struct _KvpValue KvpValue
 

A KvpValue is a union with possible types enumerated in the KvpValueType enum.


Enumeration Type Documentation

enum KvpValueType
 

Enum to enumerate possible types in the union KvpValue XXX FIXME TODO: People have asked for boolean values, e.g. in xaccAccountSetAutoInterestXfer

XXX In the long run, this should be synchronized with the core QOF types, which in turn should be synced to the g_types in GLib. Unfortuantely, this requies writing a pile of code to handle all of the different cases. An alternative might be to make kvp values inherit from the core g_types (i.e. add new core g_types) ??


Function Documentation

GSList* g_hash_table_key_value_pairs GHashTable *  table  ) 
 

Returns a GSList* of all the keys and values in a given hash table. Data elements of lists are actual hash elements, so be careful, and deallocation of the GHashTableKVPairs in the result list are the caller's responsibility. A typical sequence might look like this:

GSList *kvps = g_hash_table_key_value_pairs(hash); ... use kvps->data->key and kvps->data->val, etc. here ... g_slist_foreach(kvps, g_hash_table_kv_pair_free_gfunc, NULL); g_slist_free(kvps);

void kvp_frame_add_gint64 KvpFrame frame,
const char *  path,
gint64  ival
 

The kvp_frame_add_gint64() routine will add the value of the gint64 to the glist bag of values at the indicated path. If not all frame components of the path exist, they are created. If the value previously stored at this path was not a glist bag, then a bag will be formed there, the old value placed in the bag, and the new value added to the bag.

Similarly, the add_double, add_numeric, and add_timespec routines perform the same function, for each of the respective types.

void kvp_frame_add_str KvpFrame frame,
const char *  path,
const char *  str
 

The kvp_frame_add_str() routine will add a copy of the string to the glist bag at the indicated path. If not all frame components of the path exist, they are created. If there was another item previously stored at that path, then the path is converted to a bag, and the old value, along with the new value, is added to the bag.

Similarly, the add_guid and add_frame will make copies and add those.

The kvp_frame_add_frame_nc() routine works as above, but does *NOT* copy the frame.

void kvp_frame_add_url_encoding KvpFrame frame,
const char *  enc
 

The kvp_frame_add_url_encoding() routine will parse the value string, assuming it to be URL-encoded in the standard way, turning it into a set of key-value pairs, and adding those to the indicated frame. URL-encoded strings are the things that are returned by web browsers when a form is filled out. For example, 'start-date=June&end-date=November' consists of two keys, 'start-date' and 'end-date', which have the values 'June' and 'November', respectively. This routine also handles encoding.

This routine treats all values as strings; it does *not* attempt to perform any type-conversion.

gint kvp_frame_compare const KvpFrame fa,
const KvpFrame fb
 

Similar returns as strcmp.

KvpFrame* kvp_frame_copy const KvpFrame frame  ) 
 

Perform a deep (recursive) value copy, copying the fraame, subframes, and the values as well.

void kvp_frame_delete KvpFrame frame  ) 
 

Perform a deep (recursive) delete of the frame and any subframes.

void kvp_frame_for_each_slot KvpFrame f,
void(*  proc)(const char *key, KvpValue *value, gpointer data),
gpointer  data
 

Traverse all of the slots in the given kvp_frame. This function does not descend recursively to traverse any kvp_frames stored as slot values. You must handle that in proc, with a suitable recursive call if desired.

KvpFrame* kvp_frame_get_frame const KvpFrame frame,
const char *  path
 

Value accessor. Takes a unix-style slash-separated path as an argument, and return the KvpFrame stored at that location. If the KvpFrame does not exist, then a NULL is returned.

Note:
The semantics here have changed: In gnucash-1.8, if the KvpFrame did not exist, this function automatically created one and returned it. However, now this function will return NULL in this case and the caller has to create a KvpFrame on his own. The old functionality is now implemented by kvp_frame_get_frame_path(). This happened on 2003-09-14, revision 1.31. FIXME: Is it really a good idea to change the semantics of an existing function and move the old semantics to a new function??! It would save us a lot of trouble if the new semantics would have been available in a new function!
Returns:
The KvpFrame at the specified path, or NULL if it doesn't exist.

KvpFrame* kvp_frame_get_frame_gslist KvpFrame frame,
GSList *  key_path
 

This routine returns the last frame of the path. If the frame path doesn't exist, it is created. Note that this is *VERY DIFFERENT FROM* like kvp_frame_get_frame()

KvpFrame* kvp_frame_get_frame_path KvpFrame frame,
const char *  ,
  ...
 

This routine returns the last frame of the path. If the frame path doesn't exist, it is created. Note that this is *VERY DIFFERENT FROM* like kvp_frame_get_frame()

Note:
The semantics of this function implemented the gnucash-1.8 behaviour of kvp_frame_get_frame: In gnucash-1.8, if the KvpFrame did not exist, kvp_frame_get_frame automatically created one and returned it. However, now that one will return NULL in this case and the caller has to create a KvpFrame on his own. The old functionality is implemented by this kvp_frame_get_frame_path(). This happened on 2003-09-14, revision 1.31.

KvpFrame* kvp_frame_get_frame_slash KvpFrame frame,
const char *  path
 

This routine returns the last frame of the path. If the frame path doesn't exist, it is created. Note that this is *VERY DIFFERENT FROM* like kvp_frame_get_frame()

The kvp_frame_get_frame_slash() routine takes a single string where the keys are separated by slashes; thus, for example: /this/is/a/valid/path and///so//is////this/ Multiple slashes are compresed. Leading slash is optional. The pointers . and .. are *not* currently followed/obeyed. (This is a bug that needs fixing).

gint64 kvp_frame_get_gint64 const KvpFrame frame,
const char *  path
 

Value accessors. These all take a unix-style slash-separated path as an argument, and return the value stored at that location. If the object at the end of that path is not of the type that was asked for, then a NULL or a zero is returned. So, for example, asking for a string when the path stored an int will return a NULL. In some future date, this may be changed to a looser type system, such as perl's automatic re-typing (e.g. an integer value might be converted to a printed string representing that value).

If any part of the path does not exist, then NULL or zero will be returned.

The values returned for GUID, binary, GList, KvpFrame and string are "non-copying" -- the returned item is the actual item stored. Do not delete this item unless you take the required care to avoid possible bad pointer derefrences (i.e. core dumps). Also, be careful hanging on to those references if you are also storing at the same path names: the referenced item will be freed during the store.

That is, if you get a string value (or guid, binary or frame), and then store something else at that path, the string that you've gotten will be freed during the store (internally, by the set_*() routines), and you will be left hanging onto an invalid pointer.

KvpValue* kvp_frame_get_slot const KvpFrame frame,
const char *  key
 

Returns the KvpValue in the given KvpFrame 'frame' that is associated with 'key'. If there is no key in the frame, NULL is returned. If the value associated with the key is NULL, NULL is returned.

Pointers passed as arguments into get_slot are the responsibility of the caller. Pointers returned by get_slot are owned by the kvp_frame. Make copies as needed.

KvpValue* kvp_frame_get_slot_path KvpFrame frame,
const char *  first_key,
  ...
 

This routine return the value at the end of the path, or NULL if any portion of the path doesn't exist.

KvpValue* kvp_frame_get_slot_path_gslist KvpFrame frame,
GSList *  key_path
 

This routine return the value at the end of the path, or NULL if any portion of the path doesn't exist.

gboolean kvp_frame_is_empty KvpFrame frame  ) 
 

Return TRUE if the KvpFrame is empty

KvpFrame* kvp_frame_new void   ) 
 

Return a new empty instance of KvpFrame

KvpValue* kvp_frame_replace_slot_nc KvpFrame frame,
const char *  slot,
KvpValue new_value
 

The kvp_frame_replace_slot_nc() routine places the new value into the indicated frame, for the given key. It returns the old value, if any. It returns NULL if the slot doesn't exist, if there was some other an error, or if there was no old value. Passing in a NULL new_value has the effect of deleting that slot.

KvpValue* kvp_frame_replace_value_nc KvpFrame frame,
const char *  slot,
KvpValue new_value
 

The kvp_frame_replace_value_nc() routine places the new value at the indicated path. It returns the old value, if any. It returns NULL if there was an error, or if there was no old value. If the path doesn't exist, it is created, unless new_value is NULL. Passing in a NULL new_value has the effect of deleting the trailing slot (i.e. the trailing path element).

void kvp_frame_set_gint64 KvpFrame frame,
const char *  path,
gint64  ival
 

The kvp_frame_set_gint64() routine will store the value of the gint64 at the indicated path. If not all frame components of the path exist, they are created.

Similarly, the set_double, set_numeric, and set_timespec routines perform the same function, for each of the respective types.

void kvp_frame_set_slot KvpFrame frame,
const char *  key,
const KvpValue value
 

The kvp_frame_set_slot() routine copies the value into the frame, associating it with a copy of 'key'. Pointers passed as arguments into kvp_frame_set_slot are the responsibility of the caller; the pointers are *not* taken over or managed. The old value at this location, if any, is destroyed.

void kvp_frame_set_slot_nc KvpFrame frame,
const char *  key,
KvpValue value
 

The kvp_frame_set_slot_nc() routine puts the value (without copying it) into the frame, associating it with a copy of 'key'. This routine is handy for avoiding excess memory allocations & frees. Note that because the KvpValue was grabbed, you can't just delete unless you remove the key as well (or unless you replace the value). The old value at this location, if any, is destroyed.

void kvp_frame_set_slot_path KvpFrame frame,
const KvpValue value,
const char *  first_key,
  ...
 

The kvp_frame_set_slot_path() routine walks the hierarchy, using the key values to pick each branch. When the terminal node is reached, the value is copied into it. The old value at this location, if any, is destroyed.

void kvp_frame_set_slot_path_gslist KvpFrame frame,
const KvpValue value,
GSList *  key_path
 

The kvp_frame_set_slot_path_gslist() routine walks the hierarchy, using the key values to pick each branch. When the terminal node is reached, the value is copied into it. The old value at this location, if any, is destroyed.

void kvp_frame_set_str KvpFrame frame,
const char *  path,
const char *  str
 

The kvp_frame_set_str() routine will store a copy of the string at the indicated path. If not all frame components of the path exist, they are created. If there was another string previously stored at that path, the old copy is deleted.

Similarly, the set_guid and set_frame will make copies and store those. Old copies, if any, are deleted.

The kvp_frame_set_frame_nc() routine works as above, but does *NOT* copy the frame.

KvpFrame* kvp_frame_set_value KvpFrame frame,
const char *  path,
const KvpValue value
 

The kvp_frame_set_value() routine copies the value into the frame, at the location 'path'. If the path contains slashes '/', these are assumed to represent a sequence of keys. The returned value is a pointer to the actual frame into which the value was inserted; it is NULL if the frame couldn't be found (and thus the value wasn't inserted). The old value at this location, if any, is destroyed.

Pointers passed as arguments into this routine are the responsibility of the caller; the pointers are *not* taken over or managed.

KvpFrame* kvp_frame_set_value_nc KvpFrame frame,
const char *  path,
KvpValue value
 

The kvp_frame_set_value_nc() routine puts the value (without copying it) into the frame, putting it at the location 'path'. If the path contains slashes '/', these are assumed to represent a sequence of keys. The returned value is a pointer to the actual frame into which the value was inserted; it is NULL if the frame couldn't be found (and thus the value wasn't inserted). The old value at this location, if any, is destroyed.

This routine is handy for avoiding excess memory allocations & frees. Note that because the KvpValue was grabbed, you can't just delete unless you remove the key as well (or unless you replace the value).

gchar* kvp_frame_to_string const KvpFrame frame  ) 
 

Internal helper routines, you probably shouldn't be using these.

gint kvp_glist_compare const GList *  list1,
const GList *  list2
 

kvp_glist_compare() compares GLists of kvp_values (not to be confused with GLists of something else): it iterates over the list elements, performing a kvp_value_compare on each.

GList* kvp_glist_copy const GList *  list  ) 
 

kvp_glist_copy() performs a deep copy of a GList of kvp_values (not to be confused with GLists of something else): same as mapping kvp_value_copy() over the elements and then copying the spine.

void kvp_glist_delete GList *  list  ) 
 

kvp_glist_delete() performs a deep delete of a GList of kvp_values (not to be confused with GLists of something else): same as mapping * kvp_value_delete() over the elements and then deleting the GList.

gboolean kvp_value_binary_append KvpValue v,
void *  data,
guint64  size
 

Manipulator:

copying - but more efficient than creating a new KvpValue manually.

gint kvp_value_compare const KvpValue va,
const KvpValue vb
 

Similar returns as strcmp.

KvpValue* kvp_value_copy const KvpValue value  ) 
 

This is a deep value copy.

void kvp_value_delete KvpValue value  ) 
 

This is a deep (recursive) delete.

void* kvp_value_get_binary const KvpValue value,
guint64 *  size_return
 

Value accessor. This one is non-copying -- the caller can modify the value directly.

KvpFrame* kvp_value_get_frame const KvpValue value  ) 
 

Value accessor. This one is non-copying -- the caller can modify the value directly.

gint64 kvp_value_get_gint64 const KvpValue value  ) 
 

Value accessors. Those for GUID, binary, GList, KvpFrame and string are non-copying -- the caller can modify the value directly. Just don't free it, or you screw up everything. Note that if another value is stored at the key location that this value came from, then this value will be uncermoniously deleted, and you will be left pointing to garbage. So don't store values at the same time you are examining thier contents.

GList* kvp_value_get_glist const KvpValue value  ) 
 

Returns the GList of kvp_frame's (not to be confused with GList's of something else!) from the given kvp_frame. This one is non-copying -- the caller can modify the value directly.

GUID* kvp_value_get_guid const KvpValue value  ) 
 

Value accessor. This one is non-copying -- the caller can modify the value directly.

char* kvp_value_get_string const KvpValue value  ) 
 

Value accessor. This one is non-copying -- the caller can modify the value directly.

KvpValueType kvp_value_get_type const KvpValue value  ) 
 

You probably shouldn't be using these low-level routines

KvpValue* kvp_value_new_binary_nc void *  data,
guint64  datasize
 

value constructors (non-copying - KvpValue takes pointer ownership) values *must* have been allocated via glib allocators! (gnew, etc.)

KvpValue* kvp_value_new_frame_nc KvpFrame value  ) 
 

value constructors (non-copying - KvpValue takes pointer ownership) values *must* have been allocated via glib allocators! (gnew, etc.)

KvpValue* kvp_value_new_gint64 gint64  value  ) 
 

The following routines are constructors for kvp_value. Those with pointer arguments copy in the value. The *_nc() versions do *not* copy in thier values, but use them directly.

KvpValue* kvp_value_new_glist const GList *  value  ) 
 

Creates a KvpValue from a GList of kvp_value's! (Not to be confused with GList's of something else!)

KvpValue* kvp_value_new_glist_nc GList *  lst  ) 
 

Creates a KvpValue from a GList of kvp_value's! (Not to be confused with GList's of something else!)

This value constructor is non-copying (KvpValue takes pointer ownership). The values *must* have been allocated via glib allocators! (gnew, etc.)

KvpFrame* kvp_value_replace_frame_nc KvpValue value,
KvpFrame newframe
 

Replace old frame value with new, return old frame

GList* kvp_value_replace_glist_nc KvpValue value,
GList *  newlist
 

Replace old glist value with new, return old glist


Generated on Sun May 23 15:41:47 2004 for QOF by doxygen 1.3.6-20040222