From 36bc6d9b6bcb91166e6cb85a5eca5a1bdd2ae8a7 Mon Sep 17 00:00:00 2001 From: Christian Stimming Date: Wed, 26 Mar 2003 23:07:01 +0000 Subject: [PATCH] Updated function documentation for doxygen. git-svn-id: svn+ssh://svn.gnucash.org/repo/gnucash/trunk@8103 57a11ea4-9604-0410-9ed3-97b8803252fd --- src/engine/date.h | 242 ++++++++++++++++++++++----------------- src/engine/gnc-numeric.h | 85 +++++++++----- src/engine/kvp_frame.h | 127 +++++++++++++++----- 3 files changed, 293 insertions(+), 161 deletions(-) diff --git a/src/engine/date.h b/src/engine/date.h index 87e76e40e2..657a66b461 100644 --- a/src/engine/date.h +++ b/src/engine/date.h @@ -43,20 +43,21 @@ /** Constants *******************************************************/ +/** Enum for determining a date format */ typedef enum { - DATE_FORMAT_US, /* United states: mm/dd/yyyy */ - DATE_FORMAT_UK, /* Britain: dd/mm/yyyy */ - DATE_FORMAT_CE, /* Continental Europe: dd.mm.yyyy */ - DATE_FORMAT_ISO, /* ISO: yyyy-mm-dd */ - DATE_FORMAT_LOCALE, /* Take from locale information */ - DATE_FORMAT_CUSTOM /* Used by the check printing code */ + DATE_FORMAT_US, /**< United states: mm/dd/yyyy */ + DATE_FORMAT_UK, /**< Britain: dd/mm/yyyy */ + DATE_FORMAT_CE, /**< Continental Europe: dd.mm.yyyy */ + DATE_FORMAT_ISO, /**< ISO: yyyy-mm-dd */ + DATE_FORMAT_LOCALE, /**< Take from locale information */ + DATE_FORMAT_CUSTOM /**< Used by the check printing code */ } DateFormat; #define DATE_FORMAT_FIRST DATE_FORMAT_US #define DATE_FORMAT_LAST DATE_FORMAT_LOCALE -/* the maximum length of a string created by the date printers */ +/** The maximum length of a string created by the date printers */ #define MAX_DATE_LENGTH 11 @@ -80,11 +81,22 @@ struct timespec64 }; #endif /* SWIG */ +/** The Timespec is just like timespec (FIXME: huh? like what? + * probably: like time_t) except that we use a 64-bit signed int to + * store the seconds. This should adequately cover dates in the + * distant future as well as the distant past, as long as they're not + * more than a couple dozen times the age of the universe. Note that + * both gcc and the IBM Toronto xlC compiler (aka CSet, VisualAge, + * etc) correctly handle long long as a 64 bit quantity, even on the + * 32-bit Intel x86 and PowerPC architectures. I'm assuming that all + * the other modern compilers are clean on this issue too. */ typedef struct timespec64 Timespec; /** Prototypes ******************************************************/ +/** @name Timespec functions */ +/*@{*/ /** strict equality */ gboolean timespec_equal(const Timespec *ta, const Timespec *tb); @@ -103,102 +115,12 @@ Timespec timespec_abs(const Timespec *t); * the timepair representing midday on that day */ Timespec timespecCanonicalDayTime(Timespec t); -/** Get the numerical last date of the month. (28, 29, 30, 31) */ -int date_get_last_mday(struct tm *tm); - -/** Is the mday field the last day of the specified month.*/ -gboolean date_is_last_mday(struct tm *tm); - -/** Add a number of months to a time value and normalize. Optionally - * also track the last day of the month, i.e. 1/31 -> 2/28 -> 3/30. */ -void date_add_months (struct tm *tm, int months, gboolean track_last_day); - -/** DOCUMENT ME! */ -DateFormat getDateFormat(void); -/** DOCUMENT ME! */ -void setDateFormat(DateFormat df); -/** DOCUMENT ME! */ -const gchar *getDateFormatString(DateFormat df); -/** DOCUMENT ME! */ -const gchar *getDateTextFormatString(DateFormat df); - -/** printDate - * Convert a date as day / month / year integers into a localized string - * representation - * - * Args: buff - pointer to previously allocated character array; its size - * must be at lease MAX_DATE_LENTH bytes. - * day - day of the month as 1 ... 31 - * month - month of the year as 1 ... 12 - * year - year (4-digit) - * - * Return: nothing - * - * Globals: global dateFormat value - **/ -void printDate (char * buff, int day, int month, int year); - -/** convenience: calls through to printDate. **/ -void printDateSecs (char * buff, time_t secs); - -/** Convenience; calls through to printDate. **/ -void printGDate( char *buf, GDate *gd ); - -/** DOCUMENT ME! */ -char * xaccPrintDateSecs (time_t secs); - -/** DOCUMENT ME! */ -const char * gnc_print_date(Timespec ts); - /** Turns a time_t into a Timespec */ void timespecFromTime_t( Timespec *ts, time_t t ); /** Turns a Timespec into a time_t */ time_t timespecToTime_t (Timespec ts); -/** scanDate - * Convert a string into day / month / year integers according to - * the current dateFormat value. - * - * Args: buff - pointer to date string - * day - will store day of the month as 1 ... 31 - * month - will store month of the year as 1 ... 12 - * year - will store the year (4-digit) - * - * Return: nothing - * - * Globals: global dateFormat value - */ -void scanDate (const char *buff, int *day, int *month, int *year); - -/** dateSeparator - * Return the field separator for the current date format - * - * Args: none - * - * Return: date character - * - * Globals: global dateFormat value - */ -char dateSeparator(void); - -/** DOCUMENT ME! */ -int gnc_date_my_last_mday (int month, int year); -/** DOCUMENT ME! */ -int gnc_timespec_last_mday (Timespec ts); -/** DOCUMENT ME! */ -void gnc_timespec2dmy (Timespec ts, int *day, int *month, int *year); - -/** \warning hack alert XXX FIXME -- these date routines return incorrect - * values for dates before 1970. Most of them are good only up - * till 2038. This needs fixing ... */ -time_t xaccDMYToSec (int day, int month, int year); - -/** \warning hack alert XXX FIXME -- these date routines return incorrect - * values for dates before 1970. Most of them are good only up - * till 2038. This needs fixing ... */ -time_t xaccScanDateS (const char *buff); - /** Convert a day, month, and year to a Timespec */ Timespec gnc_dmy2timespec (int day, int month, int year); @@ -226,6 +148,21 @@ Timespec gnc_iso8601_to_timespec_gmt(const char *); * thus be used in the 'stpcpy' metaphor of string concatenation).*/ char * gnc_timespec_to_iso8601_buff (Timespec ts, char * buff); +/** DOCUMENT ME! FIXME: Probably similar to xaccDMYToSec() this date + * routine might return incorrect values for dates before 1970. */ +void gnc_timespec2dmy (Timespec ts, int *day, int *month, int *year); +/*@}*/ + + +/** Add a number of months to a time value and normalize. Optionally + * also track the last day of the month, i.e. 1/31 -> 2/28 -> 3/30. */ +void date_add_months (struct tm *tm, int months, gboolean track_last_day); + +/** \warning hack alert XXX FIXME -- these date routines return incorrect + * values for dates before 1970. Most of them are good only up + * till 2038. This needs fixing ... */ +time_t xaccDMYToSec (int day, int month, int year); + /** The gnc_timezone function returns the number of seconds *west* * of UTC represented by the tm argument, adjusted for daylight * savings time. @@ -241,6 +178,95 @@ char * gnc_timespec_to_iso8601_buff (Timespec ts, char * buff); long int gnc_timezone (struct tm *tm); +/** @name DateFormat functions */ +/*@{*/ +/** DOCUMENT ME! */ +DateFormat getDateFormat(void); +/** DOCUMENT ME! */ +void setDateFormat(DateFormat df); +/** DOCUMENT ME! */ +const gchar *getDateFormatString(DateFormat df); +/** DOCUMENT ME! */ +const gchar *getDateTextFormatString(DateFormat df); +/*@}*/ + +/** @name Date Printing/Scanning functions + * + * \warning HACK ALERT -- the scan and print routines should probably + * be moved to somewhere else. The engine really isn't involved with + * things like printing formats. This is needed mostly by the GUI and + * so on. If a file-io thing needs date handling, it should do it + * itself, instead of depending on the routines here. + */ +/*@{*/ +/** printDate + * Convert a date as day / month / year integers into a localized string + * representation + * + * Args: buff - pointer to previously allocated character array; its size + * must be at lease MAX_DATE_LENTH bytes. + * day - day of the month as 1 ... 31 + * month - month of the year as 1 ... 12 + * year - year (4-digit) + * + * Return: nothing + * + * Globals: global dateFormat value + **/ +void printDate (char * buff, int day, int month, int year); + +/** convenience: calls through to printDate(). **/ +void printDateSecs (char * buff, time_t secs); + +/** Convenience; calls through to printDate(). **/ +void printGDate( char *buf, GDate *gd ); + +/** DOCUMENT ME! */ +char * xaccPrintDateSecs (time_t secs); + +/** DOCUMENT ME! */ +const char * gnc_print_date(Timespec ts); + +/** The xaccDateUtilGetStamp() routine will take the given time in + * seconds and return a buffer containing a textual for the date. + * @param thyme The time in seconds to convert. + * @return A pointer to the generated string. + * @note The caller owns this buffer and must free it when done. */ +char *xaccDateUtilGetStamp (time_t thyme); + +/** dateSeparator + * Return the field separator for the current date format + * + * Args: none + * + * Return: date character + * + * Globals: global dateFormat value + */ +char dateSeparator(void); + +/** scanDate + * Convert a string into day / month / year integers according to + * the current dateFormat value. + * + * Args: buff - pointer to date string + * day - will store day of the month as 1 ... 31 + * month - will store month of the year as 1 ... 12 + * year - will store the year (4-digit) + * + * Return: nothing + * + * Globals: global dateFormat value + */ +void scanDate (const char *buff, int *day, int *month, int *year); + +/** \warning hack alert XXX FIXME -- these date routines return incorrect + * values for dates before 1970. Most of them are good only up + * till 2038. This needs fixing ... */ +time_t xaccScanDateS (const char *buff); +/*@}*/ + + /** @name Date Start/End Adjustment routines * Given a time value, adjust it to be the beginning or end of that day. */ @@ -306,15 +332,22 @@ time_t gnc_timet_get_day_start(time_t time_val); * seconds and adjust it to the last second of that day. */ time_t gnc_timet_get_day_end(time_t time_val); -/** The xaccDateUtilGetStamp() routine will take the given time in - * seconds and return a buffer containing a textual for the date. - * @param thyme The time in seconds to convert. - * @return A pointer to the generated string. - * @note The caller owns this buffer and must free it when done. */ -char *xaccDateUtilGetStamp (time_t thyme); +/** Get the numerical last date of the month. (28, 29, 30, 31) */ +int date_get_last_mday(struct tm *tm); + +/** Is the mday field the last day of the specified month.*/ +gboolean date_is_last_mday(struct tm *tm); + +/** DOCUMENT ME! Probably the same as date_get_last_mday() */ +int gnc_date_my_last_mday (int month, int year); +/** DOCUMENT ME! Probably the same as date_get_last_mday() */ +int gnc_timespec_last_mday (Timespec ts); +/*@}*/ /* ======================================================== */ +/** @name Today's Date */ +/*@{*/ /** The gnc_tm_get_today_start() routine takes a pointer to a struct * tm and fills it in with the first second of the today. */ void gnc_tm_get_today_start(struct tm *tm); @@ -336,8 +369,7 @@ time_t gnc_timet_get_today_end(void); * @return A pointer to the generated string. * @note The caller owns this buffer and must free it when done. */ char *xaccDateUtilGetStampNow (void); - -/** @} */ +/*@}*/ #endif /* XACC_DATE_H */ /** @} */ diff --git a/src/engine/gnc-numeric.h b/src/engine/gnc-numeric.h index 95603b38c0..b928531818 100644 --- a/src/engine/gnc-numeric.h +++ b/src/engine/gnc-numeric.h @@ -82,41 +82,75 @@ enum { #define GNC_DENOM_SIGFIGS( a ) ( ((( a ) & 0xff) << 8) | GNC_DENOM_SIGFIG) #define GNC_NUMERIC_GET_SIGFIGS( a ) ( (( a ) & 0xff00 ) >> 8) +/** @name Constructors */ +/*@{*/ /** make a gnc_numeric from numerator and denominator */ gnc_numeric gnc_numeric_create(gint64 num, gint64 denom); /** create a zero-value gnc_numeric */ gnc_numeric gnc_numeric_zero(void); +/** convert from floating-point values */ +gnc_numeric double_to_gnc_numeric(double in, gint64 denom, + gint how); + +/** Read a gnc_numeric from str, skipping any leading whitespace, and + returning a pointer to just past the last byte read. Return NULL + on error. */ +const gchar *string_to_gnc_numeric(const gchar* str, gnc_numeric *n); + /** make a special error-signalling gnc_numeric */ gnc_numeric gnc_numeric_error(int error_code); +/*@}*/ -/** check for error signal in value */ -int gnc_numeric_check(gnc_numeric a); - -/** get parts */ +/** @name Value accessors */ +/*@{*/ +/** Get parts */ gint64 gnc_numeric_num(gnc_numeric a); +/** Get parts */ gint64 gnc_numeric_denom(gnc_numeric a); -/** tests */ -int gnc_numeric_zero_p(gnc_numeric a); /* 1 if 0, 0 else */ +/** Convert to floating-point values */ +double gnc_numeric_to_double(gnc_numeric in); + +/** Convert to string. The returned buffer is to be g_free'd by the + * caller (it was allocated through g_strdup) */ +gchar *gnc_numeric_to_string(gnc_numeric n); +/*@}*/ + +/** @name Tests */ +/*@{*/ +/** Check for error signal in value. Returns GNC_ERROR_OK (==0) if + * there is no error, or any error code if there is one + * (e.g. GNC_ERROR_OVERFLOW) */ +int gnc_numeric_check(gnc_numeric a); + +/** Returns 1 if the given gnc_numeric is 0 (zeros), else returns 0. */ +int gnc_numeric_zero_p(gnc_numeric a); +/** Returns 1 if a>b, -1 if b>a, 0 if a == b */ int gnc_numeric_compare(gnc_numeric a, gnc_numeric b); int gnc_numeric_negative_p(gnc_numeric a); int gnc_numeric_positive_p(gnc_numeric a); -/** equivalence predicates : - * eq : a and b are exactly the same (same numerator and denominator) - * equal : a and b represent exactly the same number (ratio of numerator - * to denominator is exactly equal) - * same : after both are converted to DENOM using method HOW, a and b - * are equal(). +/** Equivalence predicate: Returns TRUE (1) if a and b are exactly the + * same (same numerator and denominator) */ int gnc_numeric_eq(gnc_numeric a, gnc_numeric b); +/** Equivalence predicate: Returns TRUE (1) if a and b represent + * exactly the same number (ratio of numerator to denominator is + * exactly equal) + */ int gnc_numeric_equal(gnc_numeric a, gnc_numeric b); +/** Equivalence predicate: Returns TRUE (1) if after both are + * converted to DENOM using method HOW, a and b are + * gnc_numeric_equal(). + */ int gnc_numeric_same(gnc_numeric a, gnc_numeric b, gint64 denom, gint how); +/*@}*/ -/** arithmetic operations */ +/** @name Arithmetic operations */ +/*@{*/ gnc_numeric gnc_numeric_add(gnc_numeric a, gnc_numeric b, gint64 denom, gint how); gnc_numeric gnc_numeric_sub(gnc_numeric a, gnc_numeric b, @@ -125,14 +159,19 @@ gnc_numeric gnc_numeric_mul(gnc_numeric a, gnc_numeric b, gint64 denom, gint how); gnc_numeric gnc_numeric_div(gnc_numeric a, gnc_numeric b, gint64 denom, gint how); +/** Negate the argument */ gnc_numeric gnc_numeric_neg(gnc_numeric a); +/** Return the absolute value of the argument */ gnc_numeric gnc_numeric_abs(gnc_numeric a); -/** some shortcuts for common operations */ +/** Shortcut for common operations */ gnc_numeric gnc_numeric_add_fixed(gnc_numeric a, gnc_numeric b); +/** Shortcut for common operations */ gnc_numeric gnc_numeric_sub_fixed(gnc_numeric a, gnc_numeric b); +/*@}*/ -/** arithmetic functions with exact error returns */ +/** @name Arithmetic functions with exact error returns */ +/*@{*/ gnc_numeric gnc_numeric_add_with_error(gnc_numeric a, gnc_numeric b, gint64 denom, gint how, gnc_numeric * error); @@ -145,28 +184,22 @@ gnc_numeric gnc_numeric_mul_with_error(gnc_numeric a, gnc_numeric b, gnc_numeric gnc_numeric_div_with_error(gnc_numeric a, gnc_numeric b, gint64 denom, gint how, gnc_numeric * error); +/*@}*/ +/** @name Change denominator */ +/*@{*/ /** change the denominator of a gnc_numeric value */ gnc_numeric gnc_numeric_convert(gnc_numeric in, gint64 denom, gint how); +/** change the denominator of a gnc_numeric value */ gnc_numeric gnc_numeric_convert_with_error(gnc_numeric in, gint64 denom, gint how, gnc_numeric * error); /** reduce by GCF elimination */ gnc_numeric gnc_numeric_reduce(gnc_numeric in); +/*@}*/ -/** convert to and from floating-point values */ -gnc_numeric double_to_gnc_numeric(double in, gint64 denom, - gint how); -double gnc_numeric_to_double(gnc_numeric in); - -gchar *gnc_numeric_to_string(gnc_numeric n); - -/** Read a gnc_numeric from str, skipping any leading whitespace, and - returning a pointer to just past the last byte read. Return NULL - on error. */ -const gchar *string_to_gnc_numeric(const gchar* str, gnc_numeric *n); #endif diff --git a/src/engine/kvp_frame.h b/src/engine/kvp_frame.h index 7126cb782d..b0d53f5be7 100644 --- a/src/engine/kvp_frame.h +++ b/src/engine/kvp_frame.h @@ -45,10 +45,11 @@ */ typedef struct _kvp_frame kvp_frame; -/** */ +/** A kvp_value is a union with possible types enumerated in the + * kvp_value_t enum. */ typedef struct _kvp_value kvp_value; -/** */ +/** Enum to enumerate possible types in the union kvp_value */ typedef enum { KVP_TYPE_GINT64, KVP_TYPE_DOUBLE, @@ -62,12 +63,17 @@ typedef enum { } kvp_value_t; - +/** @name kvp_frame Constructors */ +/*@{*/ /** kvp_frame functions */ kvp_frame * kvp_frame_new(void); +/** This is a deep (recursive) delete. */ void kvp_frame_delete(kvp_frame * frame); +/** This is a deep value copy. */ kvp_frame * kvp_frame_copy(const kvp_frame * frame); gboolean kvp_frame_is_empty(kvp_frame * frame); +/*@}*/ + gchar* kvp_frame_to_string(const kvp_frame *frame); gchar* binary_to_string(const void *data, guint32 size); @@ -75,21 +81,24 @@ gchar* kvp_value_glist_to_string(const GList *list); GHashTable* kvp_frame_get_hash(const kvp_frame *frame); + +/** @name kvp_frame Value Storing */ +/*@{*/ /** The kvp_frame_set_slot() routine copies the value into the frame, * associating it with 'key'. - * The kvp_frame_set_slot_nc() routine puts the value (without copying - * it) into the frame, associating it with 'key'. This routine is - * handy for avoiding excess memory allocations & frees. - * 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. + * + * Pointers passed as arguments into set_slot are the responsibility + * of the caller. */ void kvp_frame_set_slot(kvp_frame * frame, const char * key, const kvp_value * value); +/** + * The kvp_frame_set_slot_nc() routine puts the value (without copying + * it) into the frame, associating it with 'key'. This routine is + * handy for avoiding excess memory allocations & frees. + */ void kvp_frame_set_slot_nc(kvp_frame * frame, const char * key, kvp_value * value); -kvp_value * kvp_frame_get_slot(kvp_frame * frame, - const char * key); /** The kvp_frame_set_slot_path() routines walk the hierarchy, * using the key values to pick each branch. When the terminal node @@ -99,11 +108,39 @@ void kvp_frame_set_slot_path (kvp_frame *frame, const kvp_value *value, const char *first_key, ...); +/** The kvp_frame_set_slot_path() routines walk the hierarchy, + * using the key values to pick each branch. When the terminal node + * is reached, the value is copied into it. + */ void kvp_frame_set_slot_path_gslist (kvp_frame *frame, const kvp_value *value, GSList *key_path); +/*@}*/ -/** The following routines return the last frame of the path. + +/** @name kvp_frame Value Retrieval */ +/*@{*/ +/** Returns the kvp_value in the given kvp_frame 'frame' that is associated with 'key'. + * + * 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. + */ +kvp_value * kvp_frame_get_slot(kvp_frame * frame, + const char * key); + +/** This routine return the last frame of the path. + * If the frame path doesn't exist, it is created. + */ +kvp_frame * kvp_frame_get_frame (kvp_frame *frame, const char *,...); + +/** This routine return the last frame of the path. + * If the frame path doesn't exist, it is created. + */ +kvp_frame * kvp_frame_get_frame_gslist (kvp_frame *frame, + GSList *key_path); + +/** This routine return the last frame of the path. * If the frame path doesn't exist, it is created. * * The kvp_frame_get_frame_slash() routine takes a single string @@ -115,32 +152,29 @@ void kvp_frame_set_slot_path_gslist (kvp_frame *frame, * * */ -kvp_frame * kvp_frame_get_frame (kvp_frame *frame, const char *,...); - -kvp_frame * kvp_frame_get_frame_gslist (kvp_frame *frame, - GSList *key_path); - kvp_frame * kvp_frame_get_frame_slash (kvp_frame *frame, const char *path); -/** The following routines return the value at the end of the +/** This routine return the value at the end of the * path, or NULL if any portion of the path doesn't exist. */ kvp_value * kvp_frame_get_slot_path (kvp_frame *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. + */ kvp_value * kvp_frame_get_slot_path_gslist (kvp_frame *frame, GSList *key_path); -gint kvp_frame_compare(const kvp_frame *fa, const kvp_frame *fb); -gint double_compare(double v1, double v2); - -void kvp_value_delete(kvp_value * value); -kvp_value * kvp_value_copy(const kvp_value * value); /** * Similar returns as strcmp. **/ -gint kvp_value_compare(const kvp_value *va, const kvp_value *vb); +gint kvp_frame_compare(const kvp_frame *fa, const kvp_frame *fb); +/*@}*/ + + +gint double_compare(double v1, double v2); /** list convenience funcs. */ gint kvp_glist_compare(const GList * list1, const GList * list2); @@ -155,6 +189,9 @@ GList * kvp_glist_copy(const GList * list); */ void kvp_glist_delete(GList * list); + +/** @name kvp_value Constructors */ +/*@{*/ /** 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, @@ -173,9 +210,22 @@ kvp_value * kvp_value_new_frame(const kvp_frame * value); /** value constructors (non-copying - kvp_value takes pointer ownership) values *must* have been allocated via glib allocators! (gnew, etc.) */ kvp_value * kvp_value_new_binary_nc(void * data, guint64 datasize); +/** value constructors (non-copying - kvp_value takes pointer ownership) + values *must* have been allocated via glib allocators! (gnew, etc.) */ kvp_value * kvp_value_new_glist_nc(GList *lst); +/** value constructors (non-copying - kvp_value takes pointer ownership) + values *must* have been allocated via glib allocators! (gnew, etc.) */ kvp_value * kvp_value_new_frame_nc(kvp_frame * value); +/** This is a deep (recursive) delete. */ +void kvp_value_delete(kvp_value * value); +/** This is a deep value copy. */ +kvp_value * kvp_value_copy(const kvp_value * value); +/*@}*/ + + +/** @name kvp_value Value access */ +/*@{*/ /** Value accessors. Those for GUID, binary, GList, kvp_frame and string are non-copying -- the caller can modify the value directly. @@ -188,23 +238,40 @@ kvp_value_t kvp_value_get_type(const kvp_value * value); gint64 kvp_value_get_gint64(const kvp_value * value); double kvp_value_get_double(const kvp_value * value); gnc_numeric kvp_value_get_numeric(const kvp_value * value); +/** Value accessor. This one is non-copying -- the caller can modify + * the value directly. */ char * kvp_value_get_string(const kvp_value * value); +/** Value accessor. This one is non-copying -- the caller can modify + * the value directly. */ GUID * kvp_value_get_guid(const kvp_value * value); +/** Value accessor. This one is non-copying -- the caller can modify + * the value directly. */ void * kvp_value_get_binary(const kvp_value * value, guint64 * size_return); +/** Value accessor. This one is non-copying -- the caller can modify + * the value directly. */ GList * kvp_value_get_glist(const kvp_value * value); +/** Value accessor. This one is non-copying -- the caller can modify + * the value directly. */ kvp_frame * kvp_value_get_frame(const kvp_value * value); Timespec kvp_value_get_timespec(const kvp_value * value); +/** + * Similar returns as strcmp. + **/ +gint kvp_value_compare(const kvp_value *va, const kvp_value *vb); +/*@}*/ + + gchar* kvp_value_to_string(const kvp_value *val); -/** manipulators */ - +/** Manipulator: + * + * copying - but more efficient than creating a new kvp_value manually. */ gboolean kvp_value_binary_append(kvp_value *v, void *data, guint64 size); -/* copying - but more efficient than creating a new kvp_value manually. */ - -/* iterators */ +/** @name Iterators */ +/*@{*/ /** 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 @@ -214,6 +281,6 @@ void kvp_frame_for_each_slot(kvp_frame *f, kvp_value *value, gpointer data), gpointer data); - +/*@}*/ #endif