QOF: KVP: Key-Value Pairs

QOF 0.7.5

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

Files | Data Structures | Macros | Typedefs | Enumerations | Functions
KVP: Key-Value Pairs
Query Object Framework

## Files
file | kvpframe.h
| A key-value frame system.
file | kvputil-p.h
| misc odd-job kvp utils engine-private routines
file | kvputil.h
| QOF KVP utility functions.

## Data Structures
struct | GHashTableKVPair

## Macros
#define | QOF_MOD_KVP "qof-kvp"

## Typedefs
typedef struct _KvpFrame | KvpFrame
typedef struct _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_TIME, KVP_TYPE_BINARY, KVP_TYPE_GLIST, KVP_TYPE_FRAME, KVP_TYPE_BOOLEAN }
| possible types in the union KvpValue More...

## Functions
gchar * | kvp_value_to_bare_string (const KvpValue *val)
| General purpose function to convert any KvpValue to a string. More...
gchar * | kvp_value_to_string (const KvpValue *val)
| Debug version. More...
gboolean | kvp_value_binary_append (KvpValue *v, gpointer data, guint64 size)
gint | kvp_frame_compare (const KvpFrame *fa, const KvpFrame *fb)
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)

## KvpFrame Constructors
KvpFrame * | kvp_frame_new (void)
void | kvp_frame_delete (KvpFrame *frame)
KvpFrame * | kvp_frame_copy (const KvpFrame *frame)
gboolean | kvp_frame_is_empty (KvpFrame *frame)

## KvpFrame Basic Value Storing
void | kvp_frame_set_gint64 (KvpFrame *frame, const gchar *path, gint64 ival)
| store the value of the gint64 at the indicated path. More...
void | kvp_frame_set_double (KvpFrame *frame, const gchar *path, gdouble dval)
| store the value of the double at the indicated path. More...
void | kvp_frame_set_numeric (KvpFrame *frame, const gchar *path, QofNumeric nval)
| store the value of the QofNumeric at the indicated path. More...
void | kvp_frame_set_string (KvpFrame *frame, const gchar *path, const gchar *str)
| Store a copy of the string at the indicated path. More...
void | kvp_frame_set_guid (KvpFrame *frame, const gchar *path, const GUID *guid)
| Store a copy of the GUID at the indicated path. More...
void | kvp_frame_set_time (KvpFrame *frame, const gchar *path, QofTime *qt)
| Store a copy of the QofTime at the indicated path. More...
void | kvp_frame_set_boolean (KvpFrame *frame, const gchar *path, gboolean val)
| Store the value of the boolean at the indicated path. More...
void | kvp_frame_set_frame (KvpFrame *frame, const gchar *path, KvpFrame *chld)
| Store a copy of the KvpFrame at the indicated path. More...
void | kvp_frame_set_frame_nc (KvpFrame *frame, const gchar *path, KvpFrame *chld)
| Store a KvpFrame at the indicated path without copying. More...
KvpFrame * | kvp_frame_set_value (KvpFrame *frame, const gchar *path, const KvpValue *value)
| Copy the KvpValue into the frame. More...
KvpFrame * | kvp_frame_set_value_nc (KvpFrame *frame, const gchar *path, KvpValue *value)
| Store the KvpValue in the frame without copying. More...
KvpValue * | kvp_frame_replace_value_nc (KvpFrame *frame, const gchar *slot, KvpValue *new_value)

## KvpFrame Glist Bag Storing
void | kvp_frame_add_gint64 (KvpFrame *frame, const gchar *path, gint64 ival)
| add the value of the gint64 to the glist bag More...
void | kvp_frame_add_double (KvpFrame *frame, const gchar *path, gdouble dval)
| Add the value of the double to the glist bag. More...
void | kvp_frame_add_numeric (KvpFrame *frame, const gchar *path, QofNumeric nval)
| Add the value of the QofNumeric to the glist bag. More...
void | kvp_frame_add_time (KvpFrame *frame, const gchar *path, QofTime *qt)
| Add the value of the QofTime to the glist bag. More...
void | kvp_frame_add_string (KvpFrame *frame, const gchar *path, const gchar *str)
| Copy the string to the glist bag at the indicated path. More...
void | kvp_frame_add_boolean (KvpFrame *frame, const gchar *path, gboolean val)
void | kvp_frame_add_guid (KvpFrame *frame, const gchar *path, const GUID *guid)
| Copy the GUID to the glist bag at the indicated path. More...
void | kvp_frame_add_frame (KvpFrame *frame, const gchar *path, KvpFrame *chld)
| Copy the frame to the glist bag at the indicated path. More...
void | kvp_frame_add_frame_nc (KvpFrame *frame, const gchar *path, KvpFrame *chld)
| Add the frame to the glist bag without copying. More...
KvpFrame * | kvp_frame_add_value (KvpFrame *frame, const gchar *path, KvpValue *value)
| Add a copy of the value to the glist bag. More...
KvpFrame * | kvp_frame_add_value_nc (KvpFrame *frame, const gchar *path, KvpValue *value)

## KvpFrame Value Fetching
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.
gint64 | kvp_frame_get_gint64 (const KvpFrame *frame, const gchar *path)
gdouble | kvp_frame_get_double (const KvpFrame *frame, const gchar *path)
QofNumeric | kvp_frame_get_numeric (const KvpFrame *frame, const gchar *path)
gchar * | kvp_frame_get_string (const KvpFrame *frame, const gchar *path)
GUID * | kvp_frame_get_guid (const KvpFrame *frame, const gchar *path)
gpointer | kvp_frame_get_binary (const KvpFrame *frame, const gchar *path, guint64 *size_return)
gboolean | kvp_frame_get_boolean (const KvpFrame *frame, const gchar *path)
QofTime * | kvp_frame_get_time (const KvpFrame *frame, const gchar *path)
KvpValue * | kvp_frame_get_value (const KvpFrame *frame, const gchar *path)
KvpFrame * | kvp_frame_get_frame (const KvpFrame *frame, const gchar *path)
KvpFrame * | kvp_frame_get_frame_path (KvpFrame *frame, const gchar *,...)
KvpFrame * | kvp_frame_get_frame_gslist (KvpFrame *frame, GSList *key_path)
KvpFrame * | kvp_frame_get_frame_slash (KvpFrame *frame, const gchar *path)

## KvpFrame KvpValue low-level storing routines.
You probably shouldn't be using these low-level routines
    All of the kvp_frame_set_slot_*() routines set the slot values
    "destructively", in that if there was an old value there, that
    old value is destroyed (and the memory freed).  Thus, one
    should not hang on to value pointers, as these will get
    trashed if set_slot is called on the corresponding key.

    If you want the old value, use kvp_frame_replace_slot().
KvpValue * | kvp_frame_replace_slot_nc (KvpFrame *frame, const gchar *slot, KvpValue *new_value)
void | kvp_frame_set_slot (KvpFrame *frame, const gchar *key, const KvpValue *value)
void | kvp_frame_set_slot_nc (KvpFrame *frame, const gchar *key, KvpValue *value)
void | kvp_frame_set_slot_path (KvpFrame *frame, const KvpValue *value, const gchar *first_key,...)
void | kvp_frame_set_slot_path_gslist (KvpFrame *frame, const KvpValue *value, GSList *key_path)

## KvpFrame KvpValue Low-Level Retrieval Routines
You probably shouldn't be using these low-level routines 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 (const KvpFrame *frame, const gchar *key)
KvpValue * | kvp_frame_get_slot_path (KvpFrame *frame, const gchar *first_key,...)
KvpValue * | kvp_frame_get_slot_path_gslist (KvpFrame *frame, GSList *key_path)
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
The following routines are constructors for kvp_value. Those with pointer arguments copy in the value. The *_nc() versions do not copy in their values, but use them directly.
KvpValue * | kvp_value_new_gint64 (gint64 value)
KvpValue * | kvp_value_new_double (double value)
KvpValue * | kvp_value_new_numeric (QofNumeric value)
KvpValue * | kvp_value_new_string (const gchar *value)
KvpValue * | kvp_value_new_guid (const GUID *guid)
KvpValue * | kvp_value_new_time (QofTime *value)
KvpValue * | kvp_value_new_boolean (gboolean value)
KvpValue * | kvp_value_new_binary (const void *data, guint64 datasize)
KvpValue * | kvp_value_new_frame (const KvpFrame *value)
KvpValue * | kvp_value_new_glist (const GList *value)
KvpValue * | kvp_value_new_binary_nc (void *data, guint64 datasize)
KvpValue * | kvp_value_new_glist_nc (GList *lst)
KvpValue * | kvp_value_new_frame_nc (KvpFrame *value)
void | kvp_value_delete (KvpValue *value)
KvpValue * | kvp_value_copy (const KvpValue *value)
KvpFrame * | kvp_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)
gdouble | kvp_value_get_double (const KvpValue *value)
QofNumeric | kvp_value_get_numeric (const KvpValue *value)
gchar * | kvp_value_get_string (const KvpValue *value)
GUID * | kvp_value_get_guid (const KvpValue *value)
gpointer | kvp_value_get_binary (const KvpValue *value, guint64 *size_return)
GList * | kvp_value_get_glist (const KvpValue *value)
KvpFrame * | kvp_value_get_frame (const KvpValue *value)
gboolean | kvp_value_get_boolean (const KvpValue *value)
QofTime * | kvp_value_get_time (const KvpValue *value)
gint | kvp_value_compare (const KvpValue *va, const KvpValue *vb)

## Iterators
typedef void(* | KvpValueForeachCB) (const gchar *key, KvpValue *value, gpointer data)
void | kvp_frame_for_each_slot (KvpFrame *f, KvpValueForeachCB, gpointer data)

## KvpBag Bags of GUID Pointers
KvpFrame * | qof_kvp_bag_add (KvpFrame *kvp_root, const gchar *path, QofTime *qt, const gchar *first_name,...)
void | qof_kvp_bag_merge (KvpFrame *kvp_into, const gchar *intopath, KvpFrame *kvp_from, const gchar *frompath)
KvpFrame * | qof_kvp_bag_find_by_guid (KvpFrame *root, const gchar *path, const gchar *guid_name, GUID *desired_guid)
void | qof_kvp_bag_remove_frame (KvpFrame *root, const gchar *path, KvpFrame *fr)

## 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 URL handling
void | kvp_frame_add_url_encoding (KvpFrame *frame, const gchar *enc)

## 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 hierarchical.

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.

## Typedef Documentation

typedef struct _KvpFrame KvpFrame

Opaque frame structure

Definition at line 74 of file kvpframe.h.

typedef struct _KvpValue KvpValue

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

Definition at line 78 of file kvpframe.h.

typedef void(* KvpValueForeachCB) (const gchar *key, KvpValue *value, gpointer data)

Since
  0.7.2

Definition at line 770 of file kvpframe.h.

## Enumeration Type Documentation

enum KvpValueType

possible types in the union KvpValue

Todo:
  In the long run, this could be synchronised with the core QOF types, which in turn may or may not be synced to the GValue types in GLib. The QOF types currently unsupported are KVP_TYPE_GLIST and KVP_TYPE_BINARY.

Enumerator
KVP_TYPE_GINT64 | 64bit integer QofType : QOF_TYPE_INT64 GType : G_TYPE_INT64 GLib type : gint64
KVP_TYPE_DOUBLE | standard C double type QofType : QOF_TYPE_DOUBLE GType : G_TYPE_DOUBLE GLib type : gdouble
KVP_TYPE_NUMERIC | 128bit denominator/numerator maths. QofType : QOF_TYPE_NUMERIC GType : no direct equivalent, consider QOF_TYPE_DOUBLE GLib type : no direct equivalent, consider QOF_TYPE_DOUBLE
KVP_TYPE_STRING | standard C string QofType : QOF_TYPE_STRING GType : G_TYPE_STRING GLib type : gchar*
KVP_TYPE_GUID | Unique identifier. QofType : QOF_TYPE_GUID GType : no direct equivalent, can be stored as QOF_TYPE_STRING GLib : no direct equivalent, can be stored as QOF_TYPE_STRING
KVP_TYPE_TIMESPEC | Deprecated: QOF_TYPE_DATE
KVP_TYPE_TIME | 64bit time/date handling. QofType : QOF_TYPE_TIME GType : No equivalent. GLib type : GDate (not fully equivalent, see QofTime)
KVP_TYPE_BINARY | no QofType/GType/GLib equivalent.
KVP_TYPE_GLIST | no QofType/GType equivalent.
KVP_TYPE_FRAME | no QofType/GType/GLib equivalent.
KVP_TYPE_BOOLEAN | Simple boolean type. QofType : QOF_TYPE_BOOLEAN GType : G_TYPE_BOOLEAN GLib type : gboolean

Definition at line 87 of file kvpframe.h.

88 {
94 KVP_TYPE_GINT64 = 1,
100 KVP_TYPE_DOUBLE,
106 KVP_TYPE_NUMERIC,
112 KVP_TYPE_STRING,
118 KVP_TYPE_GUID,
119 #ifndef QOF_DISABLE_DEPRECATED
120
121 KVP_TYPE_TIMESPEC,
122 #endif
123
128 KVP_TYPE_TIME,
130 KVP_TYPE_BINARY,
132 KVP_TYPE_GLIST,
134 KVP_TYPE_FRAME,
140 KVP_TYPE_BOOLEAN
141 } KvpValueType;
KVP_TYPE_TIMESPEC
Definition: kvpframe.h:121
KvpValueType
KvpValueType
possible types in the union KvpValue
Definition: kvpframe.h:87
KVP_TYPE_GUID
Unique identifier.
Definition: kvpframe.h:118
KVP_TYPE_GLIST
Definition: kvpframe.h:132
KVP_TYPE_FRAME
Definition: kvpframe.h:134
KVP_TYPE_NUMERIC
128bit denominator/numerator maths.
Definition: kvpframe.h:106
KVP_TYPE_GINT64
64bit integer
Definition: kvpframe.h:94
KVP_TYPE_BOOLEAN
Simple boolean type.
Definition: kvpframe.h:140
KVP_TYPE_BINARY
Definition: kvpframe.h:130
KVP_TYPE_STRING
standard C string
Definition: kvpframe.h:112
KVP_TYPE_DOUBLE
standard C double type
Definition: kvpframe.h:100
KVP_TYPE_TIME
64bit time/date handling.
Definition: kvpframe.h:128

## 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);

Definition at line 212 of file kvputil.c.

213 {
214 GSList *result_list = NULL;
215 g_hash_table_foreach (table, kv_pair_helper, &result_list);
216 return result_list;
217 }

void kvp_frame_add_double | ( | KvpFrame * | frame,
|  | const gchar * | path,
|  | gdouble | dval
| ) |  |

Add the value of the double to the glist bag.

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.

Definition at line 601 of file kvpframe.c.

602 {
603 KvpValue *value;
604 value = kvp_value_new_double (dval);
605 frame = kvp_frame_add_value_nc (frame, path, value);
606 if (!frame)
607 kvp_value_delete (value);
608 }
KvpValue
struct _KvpValue KvpValue
Definition: kvpframe.h:78
kvp_value_delete
void kvp_value_delete(KvpValue *value)
Definition: kvpframe.c:1361

void kvp_frame_add_frame | ( | KvpFrame * | frame,
|  | const gchar * | path,
|  | KvpFrame * | chld
| ) |  |

Copy the frame 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.

Definition at line 662 of file kvpframe.c.

663 {
664 KvpValue *value;
665 value = kvp_value_new_frame (fr);
666 frame = kvp_frame_add_value_nc (frame, path, value);
667 if (!frame)
668 kvp_value_delete (value);
669 }
KvpValue
struct _KvpValue KvpValue
Definition: kvpframe.h:78
kvp_value_delete
void kvp_value_delete(KvpValue *value)
Definition: kvpframe.c:1361

void kvp_frame_add_frame_nc | ( | KvpFrame * | frame,
|  | const gchar * | path,
|  | KvpFrame * | chld
| ) |  |

Add the frame to the glist bag without copying.

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.

Definition at line 672 of file kvpframe.c.

673 {
674 KvpValue *value;
675 value = kvp_value_new_frame_nc (fr);
676 frame = kvp_frame_add_value_nc (frame, path, value);
677 if (!frame)
678 kvp_value_delete (value);
679 }
kvp_value_new_frame_nc
KvpValue * kvp_value_new_frame_nc(KvpFrame *value)
Definition: kvpframe.c:1348
KvpValue
struct _KvpValue KvpValue
Definition: kvpframe.h:78
kvp_value_delete
void kvp_value_delete(KvpValue *value)
Definition: kvpframe.c:1361

void kvp_frame_add_gint64 | ( | KvpFrame * | frame,
|  | const gchar * | path,
|  | gint64 | ival
| ) |  |

add the value of the gint64 to the glist bag

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.

Definition at line 591 of file kvpframe.c.

592 {
593 KvpValue *value;
594 value = kvp_value_new_gint64 (ival);
595 frame = kvp_frame_add_value_nc (frame, path, value);
596 if (!frame)
597 kvp_value_delete (value);
598 }
KvpValue
struct _KvpValue KvpValue
Definition: kvpframe.h:78
kvp_value_delete
void kvp_value_delete(KvpValue *value)
Definition: kvpframe.c:1361

void kvp_frame_add_guid | ( | KvpFrame * | frame,
|  | const gchar * | path,
|  | const GUID * | guid
| ) |  |

Copy the GUID 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.

Definition at line 652 of file kvpframe.c.

653 {
654 KvpValue *value;
655 value = kvp_value_new_guid (guid);
656 frame = kvp_frame_add_value_nc (frame, path, value);
657 if (!frame)
658 kvp_value_delete (value);
659 }
KvpValue
struct _KvpValue KvpValue
Definition: kvpframe.h:78
kvp_value_delete
void kvp_value_delete(KvpValue *value)
Definition: kvpframe.c:1361

void kvp_frame_add_numeric | ( | KvpFrame * | frame,
|  | const gchar * | path,
|  | QofNumeric | nval
| ) |  |

Add the value of the QofNumeric to the glist bag.

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.

Definition at line 611 of file kvpframe.c.

613 {
614 KvpValue *value;
615 value = kvp_value_new_numeric (nval);
616 frame = kvp_frame_add_value_nc (frame, path, value);
617 if (!frame)
618 kvp_value_delete (value);
619 }
KvpValue
struct _KvpValue KvpValue
Definition: kvpframe.h:78
kvp_value_delete
void kvp_value_delete(KvpValue *value)
Definition: kvpframe.c:1361

void kvp_frame_add_string | ( | KvpFrame * | frame,
|  | const gchar * | path,
|  | const gchar * | str
| ) |  |

Copy 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.

Definition at line 642 of file kvpframe.c.

643 {
644 KvpValue *value;
645 value = kvp_value_new_string (str);
646 frame = kvp_frame_add_value_nc (frame, path, value);
647 if (!frame)
648 kvp_value_delete (value);
649 }
KvpValue
struct _KvpValue KvpValue
Definition: kvpframe.h:78
kvp_value_delete
void kvp_value_delete(KvpValue *value)
Definition: kvpframe.c:1361

void kvp_frame_add_time | ( | KvpFrame * | frame,
|  | const gchar * | path,
|  | QofTime * | qt
| ) |  |

Add the value of the QofTime to the glist bag.

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.

Definition at line 622 of file kvpframe.c.

623 {
624 KvpValue *value;
625 value = kvp_value_new_time (qt);
626 frame = kvp_frame_add_value_nc (frame, path, value);
627 if (!frame)
628 kvp_value_delete (value);
629 }
KvpValue
struct _KvpValue KvpValue
Definition: kvpframe.h:78
kvp_value_delete
void kvp_value_delete(KvpValue *value)
Definition: kvpframe.c:1361

void kvp_frame_add_url_encoding | ( | KvpFrame * | frame,
|  | const gchar * | 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.

Definition at line 880 of file kvpframe.c.

881 {
882 gchar *buff, *p;
883 if (!frame || !enc)
884 return;
885
886 /* Loop over all key-value pairs in the encoded string */
887 buff = g_strdup (enc);
888 p = buff;
889 while (*p)
890 {
891 gchar *n, *v;
892 n = strchr (p, '&'); /* n = next key-value */
893 if (n)
894 *n = 0x0;
895
896 v = strchr (p, '='); /* v = pointer to value */
897 if (!v)
898 break;
899 *v = 0x0;
900 v++;
901
902 decode (p);
903 decode (v);
904 kvp_frame_set_slot_nc (frame, p, kvp_value_new_string (v));
905
906 if (!n)
907 break; /* no next key, we are done */
908 p = ++n;
909 }
910
911 g_free (buff);
912 }
kvp_frame_set_slot_nc
void kvp_frame_set_slot_nc(KvpFrame *frame, const gchar *slot, KvpValue *value)
Definition: kvpframe.c:700

KvpFrame* kvp_frame_add_value | ( | KvpFrame * | frame,
|  | const gchar * | path,
|  | KvpValue * | value
| ) |  |

Add a copy of the value to the glist bag.

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. This routine returns the pointer to the last frame (the actual frame to which the value was added), or NULL if there was an error of any sort (typically, a parse error in the path).

Definition at line 581 of file kvpframe.c.

582 {
583 value = kvp_value_copy (value);
584 frame = kvp_frame_add_value_nc (frame, path, value);
585 if (!frame)
586 kvp_value_delete (value);
587 return frame;
588 }
kvp_value_copy
KvpValue * kvp_value_copy(const KvpValue *value)
Definition: kvpframe.c:1601
kvp_value_delete
void kvp_value_delete(KvpValue *value)
Definition: kvpframe.c:1361

gint kvp_frame_compare | ( | const KvpFrame * | fa,
|  | const KvpFrame * | fb
| ) |  |

Similar returns as strcmp.

Definition at line 1757 of file kvpframe.c.

1758 {
1759 KvpFrameCompare status;
1760
1761 if (fa == fb)
1762 return 0;
1763 /* nothing is always less than something */
1764 if (!fa && fb)
1765 return -1;
1766 if (fa && !fb)
1767 return 1;
1768
1769 /* nothing is always less than something */
1770 if (!fa->hash && fb->hash)
1771 return -1;
1772 if (fa->hash && !fb->hash)
1773 return 1;
1774
1775 status.compare = 0;
1776 status.other_frame = (KvpFrame *) fb;
1777
1778 kvp_frame_for_each_slot ((KvpFrame *) fa, kvp_frame_compare_helper,
1779 &status);
1780
1781 if (status.compare != 0)
1782 return status.compare;
1783
1784 status.other_frame = (KvpFrame *) fa;
1785
1786 kvp_frame_for_each_slot ((KvpFrame *) fb, kvp_frame_compare_helper,
1787 &status);
1788
1789 return (-status.compare);
1790 }
KvpFrame
struct _KvpFrame KvpFrame
Definition: kvpframe.h:74
kvp_frame_for_each_slot
void kvp_frame_for_each_slot(KvpFrame *f, KvpValueForeachCB proc, gpointer data)
Definition: kvpframe.c:1650

KvpFrame* kvp_frame_copy | ( | const KvpFrame * | frame | ) |

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

Definition at line 156 of file kvpframe.c.

157 {
158 KvpFrame *retval = kvp_frame_new ();
159
160 if (!frame)
161 return retval;
162
163 if (frame->hash)
164 {
165 if (!init_frame_body_if_needed (retval))
166 return (NULL);
167 g_hash_table_foreach (frame->hash,
168 &kvp_frame_copy_worker, (gpointer) retval);
169 }
170 return retval;
171 }
KvpFrame
struct _KvpFrame KvpFrame
Definition: kvpframe.h:74
kvp_frame_new
KvpFrame * kvp_frame_new(void)
Definition: kvpframe.c:100

void kvp_frame_delete | ( | KvpFrame * | frame | ) |

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

Definition at line 118 of file kvpframe.c.

119 {
120 if (!frame)
121 return;
122
123 if (frame->hash)
124 {
125 /* free any allocated resource for frame or its children */
126 g_hash_table_foreach (frame->hash, &kvp_frame_delete_worker,
127 (gpointer) frame);
128
129 /* delete the hash table */
130 g_hash_table_destroy (frame->hash);
131 frame->hash = NULL;
132 }
133 g_free (frame);
134 }

void kvp_frame_for_each_slot | ( | KvpFrame * | f,
|  | KvpValueForeachCB | ,
|  | 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.

Definition at line 1650 of file kvpframe.c.

1651 {
1652 if (!f)
1653 return;
1654 if (!proc)
1655 return;
1656 if (!(f->hash))
1657 return;
1658 g_hash_table_foreach (f->hash, (GHFunc) proc, data);
1659 }

KvpFrame* kvp_frame_get_frame | ( | const KvpFrame * | frame,
|  | const gchar * | 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.

Returns
  The KvpFrame at the specified path, or NULL if it doesn't exist.

Definition at line 984 of file kvpframe.c.

985 {
986 gchar *key = NULL;
987 frame = get_trailer_or_null (frame, path, &key);
988 return kvp_value_get_frame (kvp_frame_get_slot (frame, key));
989 }
kvp_value_get_frame
KvpFrame * kvp_value_get_frame(const KvpValue *value)
Definition: kvpframe.c:1549

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 kvp_frame_get_frame()

Definition at line 1002 of file kvpframe.c.

1003 {
1004 if (!frame)
1005 return frame;
1006
1007 while (key_path)
1008 {
1009 const gchar *key = key_path->data;
1010
1011 if (!key)
1012 return frame; /* an unusual but valid exit for this routine. */
1013
1014 frame = get_or_make (frame, key);
1015 if (!frame)
1016 return frame; /* this should never happen */
1017
1018 key_path = key_path->next;
1019 }
1020 return frame; /* this is the normal exit for this func */
1021 }

KvpFrame* kvp_frame_get_frame_path | ( | KvpFrame * | frame,
|  | const gchar * | ,
|  |  | ...
| ) |  |

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 kvp_frame_get_frame()

Definition at line 1024 of file kvpframe.c.

1025 {
1026 va_list ap;
1027 if (!frame || !key)
1028 return frame;
1029
1030 va_start (ap, key);
1031
1032 while (key)
1033 {
1034 frame = get_or_make (frame, key);
1035 if (!frame)
1036 break; /* error, should never occur */
1037 key = va_arg (ap, const char *);
1038 }
1039
1040 va_end (ap);
1041 return frame;
1042 }

KvpFrame* kvp_frame_get_frame_slash | ( | KvpFrame * | frame,
|  | const gchar * | 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 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).

Definition at line 1045 of file kvpframe.c.

1046 {
1047 gchar *root;
1048 if (!frame || !key_path)
1049 return frame;
1050
1051 root = g_strdup (key_path);
1052 frame = kvp_frame_get_frame_slash_trash (frame, root);
1053 g_free (root);
1054 return frame;
1055 }

KvpValue* kvp_frame_get_slot_path | ( | KvpFrame * | frame,
|  | const gchar * | first_key,
|  |  | ...
| ) |  |

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

Definition at line 1060 of file kvpframe.c.

1061 {
1062 va_list ap;
1063 KvpValue *value;
1064 const gchar *key;
1065
1066 if (!frame || !first_key)
1067 return NULL;
1068
1069 va_start (ap, first_key);
1070
1071 key = first_key;
1072 value = NULL;
1073
1074 while (TRUE)
1075 {
1076 value = kvp_frame_get_slot (frame, key);
1077 if (!value)
1078 break;
1079
1080 key = va_arg (ap, const gchar *);
1081 if (!key)
1082 break;
1083
1084 frame = kvp_value_get_frame (value);
1085 if (!frame)
1086 {
1087 value = NULL;
1088 break;
1089 }
1090 }
1091
1092 va_end (ap);
1093
1094 return value;
1095 }
KvpValue
struct _KvpValue KvpValue
Definition: kvpframe.h:78
kvp_value_get_frame
KvpFrame * kvp_value_get_frame(const KvpValue *value)
Definition: kvpframe.c:1549

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.

Definition at line 1098 of file kvpframe.c.

1099 {
1100 if (!frame || !key_path)
1101 return NULL;
1102
1103 while (TRUE)
1104 {
1105 const gchar *key = key_path->data;
1106 KvpValue *value;
1107
1108 if (!key)
1109 return NULL;
1110
1111 value = kvp_frame_get_slot (frame, key);
1112 if (!value)
1113 return NULL;
1114
1115 key_path = key_path->next;
1116 if (!key_path)
1117 return value;
1118
1119 frame = kvp_value_get_frame (value);
1120 if (!frame)
1121 return NULL;
1122 }
1123 }
KvpValue
struct _KvpValue KvpValue
Definition: kvpframe.h:78
kvp_value_get_frame
KvpFrame * kvp_value_get_frame(const KvpValue *value)
Definition: kvpframe.c:1549

gboolean kvp_frame_is_empty | ( | KvpFrame * | frame | ) |

Return TRUE if the KvpFrame is empty

Definition at line 137 of file kvpframe.c.

138 {
139 if (!frame)
140 return TRUE;
141 if (!frame->hash)
142 return TRUE;
143 return FALSE;
144 }

KvpFrame* kvp_frame_new | ( | void |  | ) |

Return a new empty instance of KvpFrame

Definition at line 100 of file kvpframe.c.

101 {
102 KvpFrame *retval = g_new0 (KvpFrame, 1);
103
104 /* Save space until the frame is actually used */
105 retval->hash = NULL;
106 return retval;
107 }
KvpFrame
struct _KvpFrame KvpFrame
Definition: kvpframe.h:74

KvpValue* kvp_frame_replace_slot_nc | ( | KvpFrame * | frame,
|  | const gchar * | 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.

Definition at line 178 of file kvpframe.c.

180 {
181 gpointer orig_key;
182 gpointer orig_value = NULL;
183 int key_exists;
184
185 if (!frame || !slot)
186 return NULL;
187 if (!init_frame_body_if_needed (frame))
188 return NULL; /* Error ... */
189
190 key_exists = g_hash_table_lookup_extended (frame->hash, slot,
191 &orig_key, &orig_value);
192 if (key_exists)
193 {
194 g_hash_table_remove (frame->hash, slot);
195 qof_util_string_cache_remove (orig_key);
196 }
197 else
198 orig_value = NULL;
199 if (new_value)
200 g_hash_table_insert (frame->hash,
201 qof_util_string_cache_insert ((gpointer) slot), new_value);
202 return (KvpValue *) orig_value;
203 }
KvpValue
struct _KvpValue KvpValue
Definition: kvpframe.h:78
qof_util_string_cache_insert
gpointer qof_util_string_cache_insert(gconstpointer key)
Definition: qofutil.c:439
qof_util_string_cache_remove
void qof_util_string_cache_remove(gconstpointer key)
Definition: qofutil.c:432

KvpValue* kvp_frame_replace_value_nc | ( | KvpFrame * | frame,
|  | const gchar * | 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).

Definition at line 516 of file kvpframe.c.

518 {
519 KvpValue *old_value;
520 gchar *last_key;
521
522 last_key = NULL;
523 if (new_value)
524 frame = get_trailer_make (frame, key_path, &last_key);
525 else
526 frame =
527 (KvpFrame *) get_trailer_or_null (frame, key_path, &last_key);
528 if (!frame)
529 return NULL;
530
531 old_value = kvp_frame_replace_slot_nc (frame, last_key, new_value);
532 return old_value;
533 }
KvpFrame
struct _KvpFrame KvpFrame
Definition: kvpframe.h:74
KvpValue
struct _KvpValue KvpValue
Definition: kvpframe.h:78
kvp_frame_replace_slot_nc
KvpValue * kvp_frame_replace_slot_nc(KvpFrame *frame, const gchar *slot, KvpValue *new_value)
Definition: kvpframe.c:178

void kvp_frame_set_boolean | ( | KvpFrame * | frame,
|  | const gchar * | path,
|  | gboolean | val
| ) |  |

Store the value of the boolean at the indicated path.

If not all frame components of the path exist, they are created.

Definition at line 431 of file kvpframe.c.

433 {
434 KvpValue * value;
435 value = kvp_value_new_boolean (val);
436 frame = kvp_frame_set_value_nc (frame, path, value);
437 if (!frame)
438 kvp_value_delete (value);
439 }
kvp_value_new_boolean
KvpValue * kvp_value_new_boolean(gboolean value)
Definition: kvpframe.c:1226
KvpValue
struct _KvpValue KvpValue
Definition: kvpframe.h:78
kvp_frame_set_value_nc
KvpFrame * kvp_frame_set_value_nc(KvpFrame *frame, const gchar *key_path, KvpValue *value)
Store the KvpValue in the frame without copying.
Definition: kvpframe.c:486
kvp_value_delete
void kvp_value_delete(KvpValue *value)
Definition: kvpframe.c:1361

void kvp_frame_set_double | ( | KvpFrame * | frame,
|  | const gchar * | path,
|  | gdouble | dval
| ) |  |

store the value of the double at the indicated path.

If not all frame components of the path exist, they are created.

Definition at line 400 of file kvpframe.c.

401 {
402 KvpValue *value;
403 value = kvp_value_new_double (dval);
404 frame = kvp_frame_set_value_nc (frame, path, value);
405 if (!frame)
406 kvp_value_delete (value);
407 }
KvpValue
struct _KvpValue KvpValue
Definition: kvpframe.h:78
kvp_frame_set_value_nc
KvpFrame * kvp_frame_set_value_nc(KvpFrame *frame, const gchar *key_path, KvpValue *value)
Store the KvpValue in the frame without copying.
Definition: kvpframe.c:486
kvp_value_delete
void kvp_value_delete(KvpValue *value)
Definition: kvpframe.c:1361

void kvp_frame_set_frame | ( | KvpFrame * | frame,
|  | const gchar * | path,
|  | KvpFrame * | chld
| ) |  |

Store a copy of the KvpFrame at the indicated path.

If not all frame components of the path exist, they are created. If there was another QofTime previously stored at that path, the old frame is deleted.

Definition at line 464 of file kvpframe.c.

465 {
466 KvpValue *value;
467 value = kvp_value_new_frame (fr);
468 frame = kvp_frame_set_value_nc (frame, path, value);
469 if (!frame)
470 kvp_value_delete (value);
471 }
KvpValue
struct _KvpValue KvpValue
Definition: kvpframe.h:78
kvp_frame_set_value_nc
KvpFrame * kvp_frame_set_value_nc(KvpFrame *frame, const gchar *key_path, KvpValue *value)
Store the KvpValue in the frame without copying.
Definition: kvpframe.c:486
kvp_value_delete
void kvp_value_delete(KvpValue *value)
Definition: kvpframe.c:1361

void kvp_frame_set_frame_nc | ( | KvpFrame * | frame,
|  | const gchar * | path,
|  | KvpFrame * | chld
| ) |  |

Store a KvpFrame at the indicated path without copying.

If not all frame components of the path exist, they are created. If there was another QofTime previously stored at that path, the old frame is deleted.

Definition at line 474 of file kvpframe.c.

475 {
476 KvpValue *value;
477 value = kvp_value_new_frame_nc (fr);
478 frame = kvp_frame_set_value_nc (frame, path, value);
479 if (!frame)
480 kvp_value_delete (value);
481 }
kvp_value_new_frame_nc
KvpValue * kvp_value_new_frame_nc(KvpFrame *value)
Definition: kvpframe.c:1348
KvpValue
struct _KvpValue KvpValue
Definition: kvpframe.h:78
kvp_frame_set_value_nc
KvpFrame * kvp_frame_set_value_nc(KvpFrame *frame, const gchar *key_path, KvpValue *value)
Store the KvpValue in the frame without copying.
Definition: kvpframe.c:486
kvp_value_delete
void kvp_value_delete(KvpValue *value)
Definition: kvpframe.c:1361

void kvp_frame_set_gint64 | ( | KvpFrame * | frame,
|  | const gchar * | path,
|  | gint64 | ival
| ) |  |

store the value of the gint64 at the indicated path.

If not all frame components of the path exist, they are created.

Definition at line 390 of file kvpframe.c.

391 {
392 KvpValue *value;
393 value = kvp_value_new_gint64 (ival);
394 frame = kvp_frame_set_value_nc (frame, path, value);
395 if (!frame)
396 kvp_value_delete (value);
397 }
KvpValue
struct _KvpValue KvpValue
Definition: kvpframe.h:78
kvp_frame_set_value_nc
KvpFrame * kvp_frame_set_value_nc(KvpFrame *frame, const gchar *key_path, KvpValue *value)
Store the KvpValue in the frame without copying.
Definition: kvpframe.c:486
kvp_value_delete
void kvp_value_delete(KvpValue *value)
Definition: kvpframe.c:1361

void kvp_frame_set_guid | ( | KvpFrame * | frame,
|  | const gchar * | path,
|  | const GUID * | guid
| ) |  |

Store a copy of the GUID at the indicated path.

If not all frame components of the path exist, they are created. If there was another GUID previously stored at that path, the old copy is deleted.

Definition at line 453 of file kvpframe.c.

455 {
456 KvpValue *value;
457 value = kvp_value_new_guid (guid);
458 frame = kvp_frame_set_value_nc (frame, path, value);
459 if (!frame)
460 kvp_value_delete (value);
461 }
KvpValue
struct _KvpValue KvpValue
Definition: kvpframe.h:78
kvp_frame_set_value_nc
KvpFrame * kvp_frame_set_value_nc(KvpFrame *frame, const gchar *key_path, KvpValue *value)
Store the KvpValue in the frame without copying.
Definition: kvpframe.c:486
kvp_value_delete
void kvp_value_delete(KvpValue *value)
Definition: kvpframe.c:1361

void kvp_frame_set_numeric | ( | KvpFrame * | frame,
|  | const gchar * | path,
|  | QofNumeric | nval
| ) |  |

store the value of the QofNumeric at the indicated path.

If not all frame components of the path exist, they are created.

Definition at line 420 of file kvpframe.c.

422 {
423 KvpValue *value;
424 value = kvp_value_new_numeric (nval);
425 frame = kvp_frame_set_value_nc (frame, path, value);
426 if (!frame)
427 kvp_value_delete (value);
428 }
KvpValue
struct _KvpValue KvpValue
Definition: kvpframe.h:78
kvp_frame_set_value_nc
KvpFrame * kvp_frame_set_value_nc(KvpFrame *frame, const gchar *key_path, KvpValue *value)
Store the KvpValue in the frame without copying.
Definition: kvpframe.c:486
kvp_value_delete
void kvp_value_delete(KvpValue *value)
Definition: kvpframe.c:1361

void kvp_frame_set_slot | ( | KvpFrame * | frame,
|  | const gchar * | 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.

Definition at line 684 of file kvpframe.c.

686 {
687 KvpValue *new_value = NULL;
688
689 if (!frame)
690 return;
691
692 g_return_if_fail (slot && *slot != '\0');
693
694 if (value)
695 new_value = kvp_value_copy (value);
696 kvp_frame_set_slot_destructively (frame, slot, new_value);
697 }
KvpValue
struct _KvpValue KvpValue
Definition: kvpframe.h:78
kvp_value_copy
KvpValue * kvp_value_copy(const KvpValue *value)
Definition: kvpframe.c:1601

void kvp_frame_set_slot_nc | ( | KvpFrame * | frame,
|  | const gchar * | 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.

Definition at line 700 of file kvpframe.c.

702 {
703 if (!frame)
704 return;
705
706 g_return_if_fail (slot && *slot != '\0');
707
708 kvp_frame_set_slot_destructively (frame, slot, value);
709 }

void kvp_frame_set_slot_path | ( | KvpFrame * | frame,
|  | const KvpValue * | value,
|  | const gchar * | 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.

Definition at line 726 of file kvpframe.c.

728 {
729 va_list ap;
730 const gchar *key;
731
732 if (!frame)
733 return;
734
735 g_return_if_fail (first_key && *first_key != '\0');
736
737 va_start (ap, first_key);
738
739 key = first_key;
740
741 while (TRUE)
742 {
743 KvpValue *value;
744 const gchar *next_key;
745
746 next_key = va_arg (ap, const gchar *);
747 if (!next_key)
748 {
749 kvp_frame_set_slot (frame, key, new_value);
750 break;
751 }
752
753 g_return_if_fail (*next_key != '\0');
754
755 value = kvp_frame_get_slot (frame, key);
756 if (!value)
757 {
758 KvpFrame *new_frame = kvp_frame_new ();
759 KvpValue *frame_value = kvp_value_new_frame (new_frame);
760
761 kvp_frame_set_slot_nc (frame, key, frame_value);
762
763 value = kvp_frame_get_slot (frame, key);
764 if (!value)
765 break;
766 }
767
768 frame = kvp_value_get_frame (value);
769 if (!frame)
770 break;
771
772 key = next_key;
773 }
774
775 va_end (ap);
776 }
KvpFrame
struct _KvpFrame KvpFrame
Definition: kvpframe.h:74
KvpValue
struct _KvpValue KvpValue
Definition: kvpframe.h:78
kvp_frame_set_slot
void kvp_frame_set_slot(KvpFrame *frame, const gchar *slot, const KvpValue *value)
Definition: kvpframe.c:684
kvp_frame_set_slot_nc
void kvp_frame_set_slot_nc(KvpFrame *frame, const gchar *slot, KvpValue *value)
Definition: kvpframe.c:700
kvp_frame_new
KvpFrame * kvp_frame_new(void)
Definition: kvpframe.c:100
kvp_value_get_frame
KvpFrame * kvp_value_get_frame(const KvpValue *value)
Definition: kvpframe.c:1549

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.

Definition at line 779 of file kvpframe.c.

781 {
782 if (!frame || !key_path)
783 return;
784
785 while (TRUE)
786 {
787 const gchar *key = key_path->data;
788 KvpValue *value;
789
790 if (!key)
791 return;
792
793 g_return_if_fail (*key != '\0');
794
795 key_path = key_path->next;
796 if (!key_path)
797 {
798 kvp_frame_set_slot (frame, key, new_value);
799 return;
800 }
801
802 value = kvp_frame_get_slot (frame, key);
803 if (!value)
804 {
805 KvpFrame *new_frame = kvp_frame_new ();
806 KvpValue *frame_value = kvp_value_new_frame (new_frame);
807
808 kvp_frame_set_slot_nc (frame, key, frame_value);
809
810 value = kvp_frame_get_slot (frame, key);
811 if (!value)
812 return;
813 }
814
815 frame = kvp_value_get_frame (value);
816 if (!frame)
817 return;
818 }
819 }
KvpFrame
struct _KvpFrame KvpFrame
Definition: kvpframe.h:74
KvpValue
struct _KvpValue KvpValue
Definition: kvpframe.h:78
kvp_frame_set_slot
void kvp_frame_set_slot(KvpFrame *frame, const gchar *slot, const KvpValue *value)
Definition: kvpframe.c:684
kvp_frame_set_slot_nc
void kvp_frame_set_slot_nc(KvpFrame *frame, const gchar *slot, KvpValue *value)
Definition: kvpframe.c:700
kvp_frame_new
KvpFrame * kvp_frame_new(void)
Definition: kvpframe.c:100
kvp_value_get_frame
KvpFrame * kvp_value_get_frame(const KvpValue *value)
Definition: kvpframe.c:1549

void kvp_frame_set_string | ( | KvpFrame * | frame,
|  | const gchar * | path,
|  | const gchar * | str
| ) |  |

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.

Definition at line 442 of file kvpframe.c.

444 {
445 KvpValue *value;
446 value = kvp_value_new_string (str);
447 frame = kvp_frame_set_value_nc (frame, path, value);
448 if (!frame)
449 kvp_value_delete (value);
450 }
KvpValue
struct _KvpValue KvpValue
Definition: kvpframe.h:78
kvp_frame_set_value_nc
KvpFrame * kvp_frame_set_value_nc(KvpFrame *frame, const gchar *key_path, KvpValue *value)
Store the KvpValue in the frame without copying.
Definition: kvpframe.c:486
kvp_value_delete
void kvp_value_delete(KvpValue *value)
Definition: kvpframe.c:1361

void kvp_frame_set_time | ( | KvpFrame * | frame,
|  | const gchar * | path,
|  | QofTime * | qt
| ) |  |

Store a copy of the QofTime at the indicated path.

If not all frame components of the path exist, they are created. If there was another QofTime previously stored at that path, the old copy is deleted.

Definition at line 410 of file kvpframe.c.

411 {
412 KvpValue *value;
413 value = kvp_value_new_time (qt);
414 frame = kvp_frame_set_value_nc (frame, path, value);
415 if (!frame)
416 kvp_value_delete (value);
417 }
KvpValue
struct _KvpValue KvpValue
Definition: kvpframe.h:78
kvp_frame_set_value_nc
KvpFrame * kvp_frame_set_value_nc(KvpFrame *frame, const gchar *key_path, KvpValue *value)
Store the KvpValue in the frame without copying.
Definition: kvpframe.c:486
kvp_value_delete
void kvp_value_delete(KvpValue *value)
Definition: kvpframe.c:1361

KvpFrame* kvp_frame_set_value | ( | KvpFrame * | frame,
|  | const gchar * | path,
|  | const KvpValue * | value
| ) |  |

Copy the KvpValue into the frame.

If the path contains slashes '/', these are assumed to represent a sequence of keys. The old value at this location, if any, is destroyed.

Pointers passed as arguments into this routine remain the responsibility of the caller.

Parameters

  frame | The frame to hold the copied value.
  path | The location of the value in the frame.
  value | The value to be copied.

Returns
  a pointer to the actual frame into which the value was inserted or NULL if the frame could not be found.

Definition at line 499 of file kvpframe.c.

501 {
502 KvpValue *new_value = NULL;
503 gchar *last_key;
504
505 frame = get_trailer_make (frame, key_path, &last_key);
506 if (!frame)
507 return NULL;
508
509 if (value)
510 new_value = kvp_value_copy (value);
511 kvp_frame_set_slot_destructively (frame, last_key, new_value);
512 return frame;
513 }
KvpValue
struct _KvpValue KvpValue
Definition: kvpframe.h:78
kvp_value_copy
KvpValue * kvp_value_copy(const KvpValue *value)
Definition: kvpframe.c:1601

KvpFrame* kvp_frame_set_value_nc | ( | KvpFrame * | frame,
|  | const gchar * | path,
|  | KvpValue * | value
| ) |  |

Store the KvpValue in the frame without copying.

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).

Definition at line 486 of file kvpframe.c.

488 {
489 gchar *last_key;
490
491 frame = get_trailer_make (frame, key_path, &last_key);
492 if (!frame)
493 return NULL;
494 kvp_frame_set_slot_destructively (frame, last_key, value);
495 return frame;
496 }

gint kvp_glist_compare | ( | const GList * | list1,
|  | const GList * | list2
| ) |  |

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

Definition at line 1170 of file kvpframe.c.

1171 {
1172 const GList *lp1;
1173 const GList *lp2;
1174
1175 if (list1 == list2)
1176 return 0;
1177
1178 /* Nothing is always less than something */
1179 if (!list1 && list2)
1180 return -1;
1181 if (list1 && !list2)
1182 return 1;
1183
1184 lp1 = list1;
1185 lp2 = list2;
1186 while (lp1 && lp2)
1187 {
1188 KvpValue *v1 = (KvpValue *) lp1->data;
1189 KvpValue *v2 = (KvpValue *) lp2->data;
1190 gint vcmp = kvp_value_compare (v1, v2);
1191 if (vcmp != 0)
1192 return vcmp;
1193 lp1 = lp1->next;
1194 lp2 = lp2->next;
1195 }
1196 if (!lp1 && lp2)
1197 return -1;
1198 if (!lp2 && lp1)
1199 return 1;
1200 return 0;
1201 }
KvpValue
struct _KvpValue KvpValue
Definition: kvpframe.h:78
kvp_value_compare
gint kvp_value_compare(const KvpValue *kva, const KvpValue *kvb)
Definition: kvpframe.c:1662

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.

Definition at line 1148 of file kvpframe.c.

1149 {
1150 GList *retval = NULL;
1151 GList *lptr;
1152
1153 if (!list)
1154 return retval;
1155
1156 /* Duplicate the backbone of the list (this duplicates the POINTERS
1157 * to the values; we need to deep-copy the values separately) */
1158 retval = g_list_copy ((GList *) list);
1159
1160 /* This step deep-copies the values */
1161 for (lptr = retval; lptr; lptr = lptr->next)
1162 {
1163 lptr->data = kvp_value_copy (lptr->data);
1164 }
1165
1166 return retval;
1167 }
kvp_value_copy
KvpValue * kvp_value_copy(const KvpValue *value)
Definition: kvpframe.c:1601

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.

Definition at line 1130 of file kvpframe.c.

1131 {
1132 GList *node;
1133 if (!list)
1134 return;
1135
1136 /* Delete the data in the list */
1137 for (node = list; node; node = node->next)
1138 {
1139 KvpValue *val = node->data;
1140 kvp_value_delete (val);
1141 }
1142
1143 /* Free the backbone */
1144 g_list_free (list);
1145 }
KvpValue
struct _KvpValue KvpValue
Definition: kvpframe.h:78
kvp_value_delete
void kvp_value_delete(KvpValue *value)
Definition: kvpframe.c:1361

gboolean kvp_value_binary_append | ( | KvpValue * | v,
|  | gpointer | 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.

Definition at line 1662 of file kvpframe.c.

1663 {
1664 if (kva == kvb)
1665 return 0;
1666 /* nothing is always less than something */
1667 if (!kva && kvb)
1668 return -1;
1669 if (kva && !kvb)
1670 return 1;
1671
1672 if (kva->type < kvb->type)
1673 return -1;
1674 if (kva->type > kvb->type)
1675 return 1;
1676
1677 switch (kva->type)
1678 {
1679 case KVP_TYPE_GINT64:
1680 if (kva->value.int64 < kvb->value.int64)
1681 return -1;
1682 if (kva->value.int64 > kvb->value.int64)
1683 return 1;
1684 return 0;
1685 break;
1686 case KVP_TYPE_DOUBLE:
1687 return qof_util_double_compare (kva->value.dbl, kvb->value.dbl);
1688 break;
1689 case KVP_TYPE_NUMERIC:
1690 return qof_numeric_compare (kva->value.numeric,
1691 kvb->value.numeric);
1692 break;
1693 case KVP_TYPE_STRING:
1694 return strcmp (kva->value.str, kvb->value.str);
1695 break;
1696 case KVP_TYPE_GUID:
1697 return guid_compare (kva->value.guid, kvb->value.guid);
1698 break;
1699 case KVP_TYPE_BOOLEAN:
1700 {
1701 /* true > false */
1702 if (kva->value.gbool != kvb->value.gbool)
1703 return (kva->value.gbool) ? 1 : -1;
1704 return 0;
1705 break;
1706 }
1707 case KVP_TYPE_TIME :
1708 return qof_time_cmp (kva->value.qt, kvb->value.qt);
1709 break;
1710 #ifndef QOF_DISABLE_DEPRECATED
1711 case KVP_TYPE_TIMESPEC:
1712 return timespec_cmp (&(kva->value.timespec),
1713 &(kvb->value.timespec));
1714 break;
1715 #endif
1716 case KVP_TYPE_BINARY:
1717 if (kva->value.binary.datasize < kvb->value.binary.datasize)
1718 return -1;
1719 if (kva->value.binary.datasize > kvb->value.binary.datasize)
1720 return 1;
1721 return memcmp (kva->value.binary.data,
1722 kvb->value.binary.data, kva->value.binary.datasize);
1723 break;
1724 case KVP_TYPE_GLIST:
1725 return kvp_glist_compare (kva->value.list, kvb->value.list);
1726 break;
1727 case KVP_TYPE_FRAME:
1728 return kvp_frame_compare (kva->value.frame, kvb->value.frame);
1729 break;
1730 }
1731 return 0;
1732 }
KVP_TYPE_TIMESPEC
Definition: kvpframe.h:121
qof_numeric_compare
gint qof_numeric_compare(QofNumeric a, QofNumeric b)
Definition: qofnumeric.c:174
KVP_TYPE_GUID
Unique identifier.
Definition: kvpframe.h:118
kvp_frame_compare
gint kvp_frame_compare(const KvpFrame *fa, const KvpFrame *fb)
Definition: kvpframe.c:1757
kvp_glist_compare
gint kvp_glist_compare(const GList *list1, const GList *list2)
Definition: kvpframe.c:1170
KVP_TYPE_GLIST
Definition: kvpframe.h:132
KVP_TYPE_FRAME
Definition: kvpframe.h:134
KVP_TYPE_NUMERIC
128bit denominator/numerator maths.
Definition: kvpframe.h:106
qof_time_cmp
gint qof_time_cmp(const QofTime *ta, const QofTime *tb)
Definition: qoftime.c:165
KVP_TYPE_GINT64
64bit integer
Definition: kvpframe.h:94
timespec_cmp
gint timespec_cmp(const Timespec *ta, const Timespec *tb)
Definition: deprecated.c:290
KVP_TYPE_BOOLEAN
Simple boolean type.
Definition: kvpframe.h:140
KVP_TYPE_BINARY
Definition: kvpframe.h:130
qof_util_double_compare
gint qof_util_double_compare(gdouble d1, gdouble d2)
Compare two gdouble values.
Definition: qofutil.c:179
KVP_TYPE_STRING
standard C string
Definition: kvpframe.h:112
KVP_TYPE_DOUBLE
standard C double type
Definition: kvpframe.h:100
KVP_TYPE_TIME
64bit time/date handling.
Definition: kvpframe.h:128

KvpValue* kvp_value_copy | ( | const KvpValue * | value | ) |

This is a deep value copy.

Definition at line 1601 of file kvpframe.c.

1602 {
1603 if (!value)
1604 return NULL;
1605
1606 switch (value->type)
1607 {
1608 case KVP_TYPE_GINT64:
1609 return kvp_value_new_gint64 (value->value.int64);
1610 break;
1611 case KVP_TYPE_DOUBLE:
1612 return kvp_value_new_double (value->value.dbl);
1613 break;
1614 case KVP_TYPE_NUMERIC:
1615 return kvp_value_new_numeric (value->value.numeric);
1616 break;
1617 case KVP_TYPE_STRING:
1618 return kvp_value_new_string (value->value.str);
1619 break;
1620 case KVP_TYPE_GUID:
1621 return kvp_value_new_guid (value->value.guid);
1622 break;
1623 case KVP_TYPE_BOOLEAN:
1624 return NULL;
1625 return kvp_value_new_boolean (value->value.gbool);
1626 break;
1627 case KVP_TYPE_TIME :
1628 return kvp_value_new_time (value->value.qt);
1629 break;
1630 #ifndef QOF_DISABLE_DEPRECATED
1631 case KVP_TYPE_TIMESPEC:
1632 return kvp_value_new_timespec (value->value.timespec);
1633 break;
1634 #endif
1635 case KVP_TYPE_BINARY:
1636 return kvp_value_new_binary (value->value.binary.data,
1637 value->value.binary.datasize);
1638 break;
1639 case KVP_TYPE_GLIST:
1640 return kvp_value_new_glist (value->value.list);
1641 break;
1642 case KVP_TYPE_FRAME:
1643 return kvp_value_new_frame (value->value.frame);
1644 break;
1645 }
1646 return NULL;
1647 }
KVP_TYPE_TIMESPEC
Definition: kvpframe.h:121
KVP_TYPE_GUID
Unique identifier.
Definition: kvpframe.h:118
kvp_value_new_boolean
KvpValue * kvp_value_new_boolean(gboolean value)
Definition: kvpframe.c:1226
KVP_TYPE_GLIST
Definition: kvpframe.h:132
KVP_TYPE_FRAME
Definition: kvpframe.h:134
KVP_TYPE_NUMERIC
128bit denominator/numerator maths.
Definition: kvpframe.h:106
kvp_value_new_timespec
KvpValue * kvp_value_new_timespec(Timespec timespec)
Definition: deprecated.c:1482
KVP_TYPE_GINT64
64bit integer
Definition: kvpframe.h:94
kvp_value_new_glist
KvpValue * kvp_value_new_glist(const GList *value)
Definition: kvpframe.c:1309
KVP_TYPE_BOOLEAN
Simple boolean type.
Definition: kvpframe.h:140
KVP_TYPE_BINARY
Definition: kvpframe.h:130
KVP_TYPE_STRING
standard C string
Definition: kvpframe.h:112
KVP_TYPE_DOUBLE
standard C double type
Definition: kvpframe.h:100
KVP_TYPE_TIME
64bit time/date handling.
Definition: kvpframe.h:128

void kvp_value_delete | ( | KvpValue * | value | ) |

This is a deep (recursive) delete.

Definition at line 1361 of file kvpframe.c.

1362 {
1363 if (!value)
1364 return;
1365
1366 switch (value->type)
1367 {
1368 case KVP_TYPE_STRING:
1369 g_free (value->value.str);
1370 break;
1371 case KVP_TYPE_GUID:
1372 g_free (value->value.guid);
1373 break;
1374 case KVP_TYPE_BINARY:
1375 g_free (value->value.binary.data);
1376 break;
1377 case KVP_TYPE_GLIST:
1378 kvp_glist_delete (value->value.list);
1379 break;
1380 case KVP_TYPE_FRAME:
1381 kvp_frame_delete (value->value.frame);
1382 break;
1383 case KVP_TYPE_BOOLEAN:
1384 case KVP_TYPE_GINT64:
1385 case KVP_TYPE_DOUBLE:
1386 case KVP_TYPE_NUMERIC:
1387 default:
1388 break;
1389 }
1390 g_free (value);
1391 }
KVP_TYPE_GUID
Unique identifier.
Definition: kvpframe.h:118
KVP_TYPE_GLIST
Definition: kvpframe.h:132
KVP_TYPE_FRAME
Definition: kvpframe.h:134
KVP_TYPE_NUMERIC
128bit denominator/numerator maths.
Definition: kvpframe.h:106
kvp_frame_delete
void kvp_frame_delete(KvpFrame *frame)
Definition: kvpframe.c:118
KVP_TYPE_GINT64
64bit integer
Definition: kvpframe.h:94
kvp_glist_delete
void kvp_glist_delete(GList *list)
Definition: kvpframe.c:1130
KVP_TYPE_BOOLEAN
Simple boolean type.
Definition: kvpframe.h:140
KVP_TYPE_BINARY
Definition: kvpframe.h:130
KVP_TYPE_STRING
standard C string
Definition: kvpframe.h:112
KVP_TYPE_DOUBLE
standard C double type
Definition: kvpframe.h:100

gpointer kvp_value_get_binary | ( | const KvpValue * | value,
|  | guint64 * | size_return
| ) |  |

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

Definition at line 1507 of file kvpframe.c.

1508 {
1509 if (!value)
1510 {
1511 if (size_return)
1512 *size_return = 0;
1513 PERR (" no size specified");
1514 return NULL;
1515 }
1516
1517 if (value->type == KVP_TYPE_BINARY)
1518 {
1519 if (size_return)
1520 *size_return = value->value.binary.datasize;
1521 return value->value.binary.data;
1522 }
1523 else
1524 {
1525 if (size_return)
1526 *size_return = 0;
1527 PERR (" value type %d does not match KVP_TYPE_BINARY",
1528 value->type);
1529 return NULL;
1530 }
1531 }
PERR
#define PERR(format, args...)
Definition: qoflog.h:183
KVP_TYPE_BINARY
Definition: kvpframe.h:130

KvpFrame* kvp_value_get_frame | ( | const KvpValue * | value | ) |

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

Definition at line 1549 of file kvpframe.c.

1550 {
1551 if (!value)
1552 return NULL;
1553 if (value->type == KVP_TYPE_FRAME)
1554 return value->value.frame;
1555 else
1556 {
1557 PERR (" value type %d does not match KVP_TYPE_FRAME",
1558 value->type);
1559 return NULL;
1560 }
1561 }
PERR
#define PERR(format, args...)
Definition: qoflog.h:183
KVP_TYPE_FRAME
Definition: kvpframe.h:134

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 their contents.

Todo:
  kvp_value_get_ functions need to set QofError so that users can check that a NULL or zero value is actually a real value and not an error result.

Definition at line 1402 of file kvpframe.c.

1403 {
1404 if (!value)
1405 return 0;
1406 if (value->type == KVP_TYPE_GINT64)
1407 return value->value.int64;
1408 else
1409 {
1410 PERR (" value type %d does not match KVP_TYPE_GINT64",
1411 value->type);
1412 return 0;
1413 }
1414 }
PERR
#define PERR(format, args...)
Definition: qoflog.h:183
KVP_TYPE_GINT64
64bit integer
Definition: kvpframe.h:94

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.

Definition at line 1534 of file kvpframe.c.

1535 {
1536 if (!value)
1537 return NULL;
1538 if (value->type == KVP_TYPE_GLIST)
1539 return value->value.list;
1540 else
1541 {
1542 PERR (" value type %d does not match KVP_TYPE_GLIST",
1543 value->type);
1544 return NULL;
1545 }
1546 }
PERR
#define PERR(format, args...)
Definition: qoflog.h:183
KVP_TYPE_GLIST
Definition: kvpframe.h:132

GUID* kvp_value_get_guid | ( | const KvpValue * | value | ) |

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

Definition at line 1477 of file kvpframe.c.

1478 {
1479 if (!value)
1480 return NULL;
1481 if (value->type == KVP_TYPE_GUID)
1482 return value->value.guid;
1483 else
1484 {
1485 PERR (" value type %d does not match KVP_TYPE_GUID",
1486 value->type);
1487 return NULL;
1488 }
1489 }
PERR
#define PERR(format, args...)
Definition: qoflog.h:183
KVP_TYPE_GUID
Unique identifier.
Definition: kvpframe.h:118

gchar* kvp_value_get_string | ( | const KvpValue * | value | ) |

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

Definition at line 1447 of file kvpframe.c.

1448 {
1449 if (!value)
1450 return NULL;
1451 if (value->type == KVP_TYPE_STRING)
1452 return value->value.str;
1453 else
1454 {
1455 PERR (" value type %d does not match KVP_TYPE_STRING",
1456 value->type);
1457 return NULL;
1458 }
1459 }
PERR
#define PERR(format, args...)
Definition: qoflog.h:183
KVP_TYPE_STRING
standard C string
Definition: kvpframe.h:112

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_boolean | ( | gboolean | value | ) |

Since
  0.7.2

Definition at line 1226 of file kvpframe.c.

1227 {
1228 KvpValue * retval = g_new0 (KvpValue, 1);
1229 retval->type = KVP_TYPE_BOOLEAN;
1230 retval->value.gbool = value;
1231 return retval;
1232 }
KvpValue
struct _KvpValue KvpValue
Definition: kvpframe.h:78
KVP_TYPE_BOOLEAN
Simple boolean type.
Definition: kvpframe.h:140

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.)

Definition at line 1348 of file kvpframe.c.

1349 {
1350 KvpValue *retval;
1351 if (!value)
1352 return NULL;
1353
1354 retval = g_new0 (KvpValue, 1);
1355 retval->type = KVP_TYPE_FRAME;
1356 retval->value.frame = value;
1357 return retval;
1358 }
KVP_TYPE_FRAME
Definition: kvpframe.h:134
KvpValue
struct _KvpValue KvpValue
Definition: kvpframe.h:78

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!)

Definition at line 1309 of file kvpframe.c.

1310 {
1311 KvpValue *retval;
1312 if (!value)
1313 return NULL;
1314
1315 retval = g_new0 (KvpValue, 1);
1316 retval->type = KVP_TYPE_GLIST;
1317 retval->value.list = kvp_glist_copy (value);
1318 return retval;
1319 }
kvp_glist_copy
GList * kvp_glist_copy(const GList *list)
Definition: kvpframe.c:1148
KVP_TYPE_GLIST
Definition: kvpframe.h:132
KvpValue
struct _KvpValue KvpValue
Definition: kvpframe.h:78

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.)

Definition at line 1322 of file kvpframe.c.

1323 {
1324 KvpValue *retval;
1325 if (!value)
1326 return NULL;
1327
1328 retval = g_new0 (KvpValue, 1);
1329 retval->type = KVP_TYPE_GLIST;
1330 retval->value.list = value;
1331 return retval;
1332 }
KVP_TYPE_GLIST
Definition: kvpframe.h:132
KvpValue
struct _KvpValue KvpValue
Definition: kvpframe.h:78

KvpFrame* kvp_value_replace_frame_nc | ( | KvpValue * | value,
|  | KvpFrame * | newframe
| ) |  |

Replace old frame value with new, return old frame

Definition at line 1564 of file kvpframe.c.

1565 {
1566 KvpFrame *oldframe;
1567 if (!value)
1568 return NULL;
1569 if (KVP_TYPE_FRAME != value->type)
1570 {
1571 PERR (" value type %d does not match KVP_TYPE_FRAME",
1572 value->type);
1573 return NULL;
1574 }
1575 oldframe = value->value.frame;
1576 value->value.frame = newframe;
1577 return oldframe;
1578 }
PERR
#define PERR(format, args...)
Definition: qoflog.h:183
KvpFrame
struct _KvpFrame KvpFrame
Definition: kvpframe.h:74
KVP_TYPE_FRAME
Definition: kvpframe.h:134

GList* kvp_value_replace_glist_nc | ( | KvpValue * | value,
|  | GList * | newlist
| ) |  |

Replace old glist value with new, return old glist

Definition at line 1581 of file kvpframe.c.

1582 {
1583 GList *oldlist;
1584 if (!value)
1585 return NULL;
1586 if (KVP_TYPE_GLIST != value->type)
1587 {
1588 PERR (" value type %d does not match KVP_TYPE_GLIST",
1589 value->type);
1590 return NULL;
1591 }
1592
1593 oldlist = value->value.list;
1594 value->value.list = newlist;
1595 return oldlist;
1596 }
PERR
#define PERR(format, args...)
Definition: qoflog.h:183
KVP_TYPE_GLIST
Definition: kvpframe.h:132

gchar* kvp_value_to_bare_string | ( | const KvpValue * | val | ) |

General purpose function to convert any KvpValue to a string.

Only the bare string is returned, there is no debugging information.

Definition at line 1848 of file kvpframe.c.

1849 {
1850 gchar *tmp1;
1851 gchar *tmp2;
1852 const gchar *ctmp;
1853
1854 g_return_val_if_fail (val, NULL);
1855 tmp1 = g_strdup ("");
1856 switch (kvp_value_get_type (val))
1857 {
1858 case KVP_TYPE_GINT64:
1859 {
1860 return g_strdup_printf ("%" G_GINT64_FORMAT,
1861 kvp_value_get_gint64 (val));
1862 break;
1863 }
1864 case KVP_TYPE_DOUBLE:
1865 {
1866 return g_strdup_printf ("(%g)", kvp_value_get_double (val));
1867 break;
1868 }
1869 case KVP_TYPE_NUMERIC:
1870 {
1871 tmp1 = qof_numeric_to_string (kvp_value_get_numeric (val));
1872 tmp2 = g_strdup_printf ("%s", tmp1 ? tmp1 : "");
1873 g_free (tmp1);
1874 return tmp2;
1875 break;
1876 }
1877 case KVP_TYPE_STRING:
1878 {
1879 tmp1 = kvp_value_get_string (val);
1880 return g_strdup_printf ("%s", tmp1 ? tmp1 : "");
1881 break;
1882 }
1883 case KVP_TYPE_GUID:
1884 {
1885 ctmp = guid_to_string (kvp_value_get_guid (val));
1886 tmp2 = g_strdup_printf ("%s", ctmp ? ctmp : "");
1887 return tmp2;
1888 break;
1889 }
1890 #ifndef QOF_DISABLE_DEPRECATED
1891 case KVP_TYPE_TIMESPEC:
1892 {
1893 time_t t;
1894 t = timespecToTime_t (kvp_value_get_timespec (val));
1895 qof_date_format_set (QOF_DATE_FORMAT_UTC);
1896 return qof_print_date (t);
1897 break;
1898 }
1899 #endif
1900 case KVP_TYPE_BOOLEAN :
1901 return (kvp_value_get_boolean (val)) ? "TRUE" : "FALSE";
1902 case KVP_TYPE_BINARY:
1903 {
1904 guint64 len;
1905 gpointer data;
1906 data = kvp_value_get_binary (val, &len);
1907 tmp1 = binary_to_string (data, len);
1908 return g_strdup_printf ("%s", tmp1 ? tmp1 : "");
1909 break;
1910 }
1911 case KVP_TYPE_GLIST:
1912 /* borked. kvp_value_glist_to_string is a debug fcn */
1913 {
1914 tmp1 = kvp_value_glist_to_string (kvp_value_get_glist (val));
1915 tmp2 = g_strdup_printf ("%s", tmp1 ? tmp1 : "");
1916 g_free (tmp1);
1917 return tmp2;
1918 break;
1919 }
1920 case KVP_TYPE_FRAME:
1921 {
1922 KvpFrame *frame;
1923
1924 frame = kvp_value_get_frame (val);
1925 if (frame->hash)
1926 {
1927 tmp1 = g_strdup ("");
1928 g_hash_table_foreach (frame->hash,
1929 kvp_frame_to_bare_string_helper, &tmp1);
1930 }
1931 return tmp1;
1932 break;
1933 }
1934 default:
1935 return g_strdup_printf (" ");
1936 break;
1937 }
1938 }
kvp_value_get_guid
GUID * kvp_value_get_guid(const KvpValue *value)
Definition: kvpframe.c:1477
KVP_TYPE_TIMESPEC
Definition: kvpframe.h:121
QOF_DATE_FORMAT_UTC
#define QOF_DATE_FORMAT_UTC
QOF UTC format, xsd:date compatible. QOF_UTC_DATE_FORMAT "%Y-%m-%dT%H:%M:%SZ".
Definition: qofdate.h:277
kvp_value_get_timespec
Timespec kvp_value_get_timespec(const KvpValue *value)
Definition: deprecated.c:1493
KVP_TYPE_GUID
Unique identifier.
Definition: kvpframe.h:118
KvpFrame
struct _KvpFrame KvpFrame
Definition: kvpframe.h:74
KVP_TYPE_GLIST
Definition: kvpframe.h:132
KVP_TYPE_FRAME
Definition: kvpframe.h:134
kvp_value_get_binary
void * kvp_value_get_binary(const KvpValue *value, guint64 *size_return)
Definition: kvpframe.c:1507
KVP_TYPE_NUMERIC
128bit denominator/numerator maths.
Definition: kvpframe.h:106
kvp_value_get_gint64
gint64 kvp_value_get_gint64(const KvpValue *value)
Definition: kvpframe.c:1402
guid_to_string
const char * guid_to_string(const GUID *guid)
Definition: guid.c:611
KVP_TYPE_GINT64
64bit integer
Definition: kvpframe.h:94
kvp_value_get_glist
GList * kvp_value_get_glist(const KvpValue *value)
Definition: kvpframe.c:1534
kvp_value_get_string
gchar * kvp_value_get_string(const KvpValue *value)
Definition: kvpframe.c:1447
qof_numeric_to_string
gchar * qof_numeric_to_string(QofNumeric n)
Definition: qofnumeric.c:1089
KVP_TYPE_BOOLEAN
Simple boolean type.
Definition: kvpframe.h:140
KVP_TYPE_BINARY
Definition: kvpframe.h:130
timespecToTime_t
time_t timespecToTime_t(Timespec ts)
Definition: deprecated.c:315
qof_date_format_set
void qof_date_format_set(QofDateFormat df)
Definition: deprecated.c:1427
KVP_TYPE_STRING
standard C string
Definition: kvpframe.h:112
kvp_value_get_frame
KvpFrame * kvp_value_get_frame(const KvpValue *value)
Definition: kvpframe.c:1549
KVP_TYPE_DOUBLE
standard C double type
Definition: kvpframe.h:100
qof_print_date
char * qof_print_date(time_t secs)
Definition: deprecated.c:767

gchar* kvp_value_to_string | ( | const KvpValue * | val | ) |

Debug version.

This version is used only by ::qof_query_printValueForParam, itself a debugging and development utility function.

Definition at line 1941 of file kvpframe.c.

1942 {
1943 gchar *tmp1;
1944 gchar *tmp2;
1945 const gchar *ctmp;
1946
1947 g_return_val_if_fail (val, NULL);
1948
1949 switch (kvp_value_get_type (val))
1950 {
1951 case KVP_TYPE_GINT64:
1952 {
1953 return g_strdup_printf ("KVP_VALUE_GINT64(%" G_GINT64_FORMAT ")",
1954 kvp_value_get_gint64 (val));
1955 break;
1956 }
1957 case KVP_TYPE_DOUBLE:
1958 {
1959 return g_strdup_printf ("KVP_VALUE_DOUBLE(%g)",
1960 kvp_value_get_double (val));
1961 break;
1962 }
1963 case KVP_TYPE_NUMERIC:
1964 {
1965 tmp1 = qof_numeric_to_string (kvp_value_get_numeric (val));
1966 tmp2 = g_strdup_printf ("KVP_VALUE_NUMERIC(%s)", tmp1 ? tmp1 : "");
1967 g_free (tmp1);
1968 return tmp2;
1969 break;
1970 }
1971 case KVP_TYPE_STRING:
1972 {
1973 tmp1 = kvp_value_get_string (val);
1974 return g_strdup_printf ("KVP_VALUE_STRING(%s)", tmp1 ? tmp1 : "");
1975 break;
1976 }
1977 case KVP_TYPE_GUID:
1978 {
1979 /* THREAD-UNSAFE */
1980 ctmp = guid_to_string (kvp_value_get_guid (val));
1981 tmp2 = g_strdup_printf ("KVP_VALUE_GUID(%s)", ctmp ? ctmp : "");
1982 return tmp2;
1983 break;
1984 }
1985 #ifndef QOF_DISABLE_DEPRECATED
1986 case KVP_TYPE_TIMESPEC:
1987 {
1988 tmp1 = g_new0 (gchar, 40);
1989 gnc_timespec_to_iso8601_buff (kvp_value_get_timespec (val), tmp1);
1990 tmp2 = g_strdup_printf ("KVP_VALUE_TIMESPEC(%s)", tmp1);
1991 g_free (tmp1);
1992 return tmp2;
1993 break;
1994 }
1995 #endif
1996 case KVP_TYPE_BINARY:
1997 {
1998 guint64 len;
1999 gpointer data;
2000 data = kvp_value_get_binary (val, &len);
2001 tmp1 = binary_to_string (data, len);
2002 return g_strdup_printf ("KVP_VALUE_BINARY(%s)",
2003 tmp1 ? tmp1 : "");
2004 break;
2005 }
2006 case KVP_TYPE_GLIST:
2007 {
2008 tmp1 = kvp_value_glist_to_string (kvp_value_get_glist (val));
2009 tmp2 = g_strdup_printf ("KVP_VALUE_GLIST(%s)", tmp1 ? tmp1 : "");
2010 g_free (tmp1);
2011 return tmp2;
2012 break;
2013 }
2014 case KVP_TYPE_FRAME:
2015 {
2016 tmp1 = kvp_frame_to_string (kvp_value_get_frame (val));
2017 tmp2 = g_strdup_printf ("KVP_VALUE_FRAME(%s)", tmp1 ? tmp1 : "");
2018 g_free (tmp1);
2019 return tmp2;
2020 break;
2021 }
2022 default:
2023 return g_strdup_printf (" ");
2024 break;
2025 }
2026 }
kvp_value_get_guid
GUID * kvp_value_get_guid(const KvpValue *value)
Definition: kvpframe.c:1477
KVP_TYPE_TIMESPEC
Definition: kvpframe.h:121
kvp_value_get_timespec
Timespec kvp_value_get_timespec(const KvpValue *value)
Definition: deprecated.c:1493
KVP_TYPE_GUID
Unique identifier.
Definition: kvpframe.h:118
KVP_TYPE_GLIST
Definition: kvpframe.h:132
KVP_TYPE_FRAME
Definition: kvpframe.h:134
kvp_value_get_binary
void * kvp_value_get_binary(const KvpValue *value, guint64 *size_return)
Definition: kvpframe.c:1507
KVP_TYPE_NUMERIC
128bit denominator/numerator maths.
Definition: kvpframe.h:106
kvp_value_get_gint64
gint64 kvp_value_get_gint64(const KvpValue *value)
Definition: kvpframe.c:1402
guid_to_string
const char * guid_to_string(const GUID *guid)
Definition: guid.c:611
KVP_TYPE_GINT64
64bit integer
Definition: kvpframe.h:94
kvp_value_get_glist
GList * kvp_value_get_glist(const KvpValue *value)
Definition: kvpframe.c:1534
kvp_value_get_string
gchar * kvp_value_get_string(const KvpValue *value)
Definition: kvpframe.c:1447
qof_numeric_to_string
gchar * qof_numeric_to_string(QofNumeric n)
Definition: qofnumeric.c:1089
KVP_TYPE_BINARY
Definition: kvpframe.h:130
KVP_TYPE_STRING
standard C string
Definition: kvpframe.h:112
kvp_value_get_frame
KvpFrame * kvp_value_get_frame(const KvpValue *value)
Definition: kvpframe.c:1549
KVP_TYPE_DOUBLE
standard C double type
Definition: kvpframe.h:100
gnc_timespec_to_iso8601_buff
gchar * gnc_timespec_to_iso8601_buff(Timespec ts, gchar *buff)
Definition: deprecated.c:1197

KvpFrame* qof_kvp_bag_add | ( | KvpFrame * | kvp_root,
|  | const gchar * | path,
|  | QofTime * | qt,
|  | const gchar * | first_name,
|  |  | ...
| ) |  |

The qof_kvp_bag_add() routine is used to maintain a collection of pointers in a kvp tree.

The thing being pointed at is uniquely identified by its GUID. This routine is typically used to create a linked list, and/or a collection of pointers to objects that are 'related' to each other in some way.

The var-args should be pairs of strings (const char *) followed by the corresponding GUID pointer (const GUID *). Terminate the varargs with a NULL as the last string argument.

The actual 'pointer' is stored in a subdirectory in a bag located at the node directory 'path'. A 'bag' is merely a collection of (unamed) values. The name of our bag is 'path'. A bag can contain any kind of values, including frames. This routine will create a frame, and put it in the bag. The frame will contain named data from the subroutine arguments. Thus, for example:

qof_kvp_array (kvp, "foo", secs, "acct_guid", aguid, "book_guid", bguid, NULL);

will create a frame containing "/acct_guid" and "/book_guid", whose values are aguid and bguid respecitvely. The frame will also contain "/date", whose value will be secs. This frame will be placed into the bag located at "foo".

This routine returns a pointer to the frame that was created, or NULL if an error occured.

Definition at line 67 of file kvputil.c.

69 {
70 KvpFrame *cwd;
71 va_list ap;
72 va_start (ap, first_name);
73 cwd = qof_kvp_array_va (pwd, path, qt, first_name, ap);
74 va_end (ap);
75 return cwd;
76 }
KvpFrame
struct _KvpFrame KvpFrame
Definition: kvpframe.h:74

KvpFrame* qof_kvp_bag_find_by_guid | ( | KvpFrame * | root,
|  | const gchar * | path,
|  | const gchar * | guid_name,
|  | GUID * | desired_guid
| ) |  |

The qof_kvp_bag_find_by_guid() routine examines the bag pointed located at root. It looks for a frame in that bag that has the guid value of "desired_guid" filed under the key name "guid_name". If it finds that matching guid, then it returns a pointer to the KVP frame that contains it. If it is not found, or if there is any other error, NULL is returned.

Definition at line 89 of file kvputil.c.

91 {
92 KvpValue *arr;
93 KvpValueType valtype;
94 GList *node;
95
96 arr = kvp_frame_get_value (root, path);
97 valtype = kvp_value_get_type (arr);
98 if (KVP_TYPE_FRAME == valtype)
99 {
100 MATCH_GUID (arr);
101 return NULL;
102 }
103
104 /* Its got to be a single isolated frame, or a list of them. */
105 if (KVP_TYPE_GLIST != valtype)
106 return NULL;
107
108 for (node = kvp_value_get_glist (arr); node; node = node->next)
109 {
110 KvpValue *va = node->data;
111 MATCH_GUID (va);
112 }
113 return NULL;
114 }
KvpValueType
KvpValueType
possible types in the union KvpValue
Definition: kvpframe.h:87
KVP_TYPE_GLIST
Definition: kvpframe.h:132
KVP_TYPE_FRAME
Definition: kvpframe.h:134
KvpValue
struct _KvpValue KvpValue
Definition: kvpframe.h:78
kvp_value_get_glist
GList * kvp_value_get_glist(const KvpValue *value)
Definition: kvpframe.c:1534

void qof_kvp_bag_merge | ( | KvpFrame * | kvp_into,
|  | const gchar * | intopath,
|  | KvpFrame * | kvp_from,
|  | const gchar * | frompath
| ) |  |

The qof_kvp_bag_merge() routine will move the bag contents from the 'kvp_from', to the 'into' bag. It will then delete the 'from' bag from the kvp tree.

Definition at line 186 of file kvputil.c.

188 {
189 KvpFrame *fr;
190
191 fr = qof_kvp_bag_get_first (kvp_from, frompath);
192 while (fr)
193 {
194 qof_kvp_bag_remove_frame (kvp_from, frompath, fr);
195 kvp_frame_add_frame_nc (kvp_into, intopath, fr);
196 fr = qof_kvp_bag_get_first (kvp_from, frompath);
197 }
198 }
kvp_frame_add_frame_nc
void kvp_frame_add_frame_nc(KvpFrame *frame, const gchar *path, KvpFrame *fr)
Add the frame to the glist bag without copying.
Definition: kvpframe.c:672
KvpFrame
struct _KvpFrame KvpFrame
Definition: kvpframe.h:74
qof_kvp_bag_remove_frame
void qof_kvp_bag_remove_frame(KvpFrame *root, const gchar *path, KvpFrame *fr)
Definition: kvputil.c:119

void qof_kvp_bag_remove_frame | ( | KvpFrame * | root,
|  | const gchar * | path,
|  | KvpFrame * | fr
| ) |  |

Remove the given frame from the bag. The frame is removed, however, it is not deleted. Note that the frame pointer must be a pointer to the actual frame (for example, as returned by gnc_kvp_bag_find_by_guid() for by gnc_kvp_bag_add()), and not some copy of the frame.

Definition at line 119 of file kvputil.c.

120 {
121 KvpValue *arr;
122 KvpValueType valtype;
123 GList *node, *listhead;
124
125 arr = kvp_frame_get_value (root, path);
126 valtype = kvp_value_get_type (arr);
127 if (KVP_TYPE_FRAME == valtype)
128 {
129 if (fr == kvp_value_get_frame (arr))
130 {
131 KvpValue *old_val =
132 kvp_frame_replace_value_nc (root, path, NULL);
133 kvp_value_replace_frame_nc (old_val, NULL);
134 kvp_value_delete (old_val);
135 }
136 return;
137 }
138
139 /* Its got to be a single isolated frame, or a list of them. */
140 if (KVP_TYPE_GLIST != valtype)
141 return;
142
143 listhead = kvp_value_get_glist (arr);
144 for (node = listhead; node; node = node->next)
145 {
146 KvpValue *va = node->data;
147 if (fr == kvp_value_get_frame (va))
148 {
149 listhead = g_list_remove_link (listhead, node);
150 g_list_free_1 (node);
151 kvp_value_replace_glist_nc (arr, listhead);
152 kvp_value_replace_frame_nc (va, NULL);
153 kvp_value_delete (va);
154 return;
155 }
156 }
157 }
kvp_value_replace_glist_nc
GList * kvp_value_replace_glist_nc(KvpValue *value, GList *newlist)
Definition: kvpframe.c:1581
KvpValueType
KvpValueType
possible types in the union KvpValue
Definition: kvpframe.h:87
KVP_TYPE_GLIST
Definition: kvpframe.h:132
KVP_TYPE_FRAME
Definition: kvpframe.h:134
kvp_frame_replace_value_nc
KvpValue * kvp_frame_replace_value_nc(KvpFrame *frame, const gchar *key_path, KvpValue *new_value)
Definition: kvpframe.c:516
KvpValue
struct _KvpValue KvpValue
Definition: kvpframe.h:78
kvp_value_get_glist
GList * kvp_value_get_glist(const KvpValue *value)
Definition: kvpframe.c:1534
kvp_value_replace_frame_nc
KvpFrame * kvp_value_replace_frame_nc(KvpValue *value, KvpFrame *newframe)
Definition: kvpframe.c:1564
kvp_value_get_frame
KvpFrame * kvp_value_get_frame(const KvpValue *value)
Definition: kvpframe.c:1549
kvp_value_delete
void kvp_value_delete(KvpValue *value)
Definition: kvpframe.c:1361