Misc Utilities
[Query Object Framework]


Files

file  gnc-engine-util.h
 QOF utility functions (This file is due to be renamed qofutil.h in libqof2. It will remain as a placeholder during libqof1.).

typedef enum as string macros

#define ENUM_BODY(name, value)   name value,
#define AS_STRING_CASE(name, value)   case name: { return #name; }
#define FROM_STRING_CASE(name, value)
#define DEFINE_ENUM(name, list)
#define AS_STRING_DEC(name, list)   const char* name##asString(name n);
#define AS_STRING_FUNC(name, list)
#define FROM_STRING_DEC(name, list)
#define FROM_STRING_FUNC(name, list)

enum as string with no typedef

Similar but used when the enum is NOT a typedef note the LACK of a define_enum macro - don't use one!

ENUM_BODY is used in both types.

#define FROM_STRING_DEC_NON_TYPEDEF(name, list)
#define FROM_STRING_CASE_NON_TYPEDEF(name, value)   if (strcmp(str, #name) == 0) { *type = name; }
#define FROM_STRING_FUNC_NON_TYPEDEF(name, list)
#define AS_STRING_DEC_NON_TYPEDEF(name, list)   const char* name##asString(enum name n);
#define AS_STRING_FUNC_NON_TYPEDEF(name, list)
#define AS_STRING_CASE_NON_TYPEDEF(name, value)   case name: { return #name; }

Convenience wrappers

void qof_init (void)
 Initialise the Query Object Framework.
void qof_close (void)
 Safely close down the Query Object Framework.

Defines

#define SAFE_STRCMP_REAL(fcn, da, db)
#define SAFE_STRCMP(da, db)   SAFE_STRCMP_REAL(strcmp,(da),(db))
#define SAFE_STRCASECMP(da, db)   SAFE_STRCMP_REAL(strcasecmp,(da),(db))
#define GNC_SCANF_LLD   "%qd"
#define stpcpy   gnc_stpcpy
#define CACHE_INSERT(str)   gnc_string_cache_insert((gpointer)(str));
#define CACHE_REMOVE(str)   gnc_string_cache_remove((str));

Functions

int safe_strcmp (const char *da, const char *db)
int safe_strcasecmp (const char *da, const char *db)
int null_strcmp (const char *da, const char *db)
char * strncasestr (const char *str1, const char *str2, size_t len)
char * strcasestr (const char *str1, const char *str2)
char * ultostr (unsigned long val, int base)
gboolean gnc_strisnum (const char *s)
char * gnc_stpcpy (char *dest, const char *src)
const char * qof_util_whitespace_filter (const char *val)
int qof_util_bool_to_int (const char *val)
GCache * gnc_engine_get_string_cache (void)
void gnc_engine_string_cache_destroy (void)
void gnc_string_cache_remove (gconstpointer key)
gpointer gnc_string_cache_insert (gpointer key)

Define Documentation

#define AS_STRING_FUNC (  name,
list   ) 
 

Value:

const char* name##asString(name n) {       \
        switch (n) {                     \
            list(AS_STRING_CASE)         \
            default: return "";  } }

Definition at line 94 of file gnc-engine-util.h.

#define AS_STRING_FUNC_NON_TYPEDEF (  name,
list   ) 
 

Value:

const char* name##asString(enum name n) {        \
        switch (n) {                     \
            list(AS_STRING_CASE_NON_TYPEDEF)         \
           default: return ""; } }

Definition at line 138 of file gnc-engine-util.h.

#define DEFINE_ENUM (  name,
list   ) 
 

Value:

typedef enum {                       \
        list(ENUM_BODY)                  \
    }name;

Definition at line 86 of file gnc-engine-util.h.

#define FROM_STRING_CASE (  name,
value   ) 
 

Value:

if (strcmp(str, #name) == 0) {       \
        return name;  }

Definition at line 82 of file gnc-engine-util.h.

#define FROM_STRING_DEC (  name,
list   ) 
 

Value:

name name##fromString                \
    (const char* str);

Definition at line 100 of file gnc-engine-util.h.

#define FROM_STRING_DEC_NON_TYPEDEF (  name,
list   ) 
 

Value:

void name##fromString                          \
        (const char* str, enum name *type);

Definition at line 122 of file gnc-engine-util.h.

#define FROM_STRING_FUNC (  name,
list   ) 
 

Value:

name name##fromString                \
    (const char* str) {                  \
    if(str == NULL) { return 0; }        \
        list(FROM_STRING_CASE)           \
        return 0;  }

Definition at line 104 of file gnc-engine-util.h.

#define FROM_STRING_FUNC_NON_TYPEDEF (  name,
list   ) 
 

Value:

void name##fromString                          \
        (const char* str, enum name *type) {         \
   if(str == NULL) { return; }                    \
    list(FROM_STRING_CASE_NON_TYPEDEF) }

Definition at line 129 of file gnc-engine-util.h.

#define SAFE_STRCASECMP (  da,
db   )     SAFE_STRCMP_REAL(strcasecmp,(da),(db))
 

Deprecated:
use safe_strcasecmp()

Definition at line 71 of file gnc-engine-util.h.

#define SAFE_STRCMP (  da,
db   )     SAFE_STRCMP_REAL(strcmp,(da),(db))
 

Deprecated:
use safe_strcmp()

Definition at line 69 of file gnc-engine-util.h.

#define SAFE_STRCMP_REAL (  fcn,
da,
db   ) 
 

Value:

{    \
  if ((da) && (db)) {                    \
    if ((da) != (db)) {                  \
      int retval = fcn ((da), (db));     \
      /* if strings differ, return */    \
      if (retval) return retval;         \
    }                                    \
  } else                                 \
  if ((!(da)) && (db)) {                 \
    return -1;                           \
  } else                                 \
  if ((da) && (!(db))) {                 \
    return +1;                           \
  }                                      \
}
Deprecated:
Use the function versions, safe_strcmp() and safe_strcasecmp(). These macros will be made private in libqof2.
If the pointer arguments are equal, the macro does nothing and safe_strcmp / safe_strcasecmp return 0.

These macros change program control flow and are not good substitutes for the function equivalents.

Definition at line 52 of file gnc-engine-util.h.

Function Documentation

GCache* gnc_engine_get_string_cache (  void   ) 
 

Deprecated:
use qof_init instead.
Get the gnc_string_cache. Create it if it doesn't exist already.

Definition at line 250 of file gnc-engine-util.c.

00251 {
00252     if(!gnc_string_cache) {
00253         gnc_string_cache = g_cache_new(
00254             (GCacheNewFunc) g_strdup, /* value_new_func     */
00255             g_free,                   /* value_destroy_func */
00256             (GCacheDupFunc) g_strdup, /* key_dup_func       */
00257             g_free,                   /* key_destroy_func   */
00258             g_str_hash,               /* hash_key_func      */
00259             g_str_hash,               /* hash_value_func    */
00260             g_str_equal);             /* key_equal_func     */
00261     }
00262     return gnc_string_cache;
00263 }

void gnc_engine_string_cache_destroy (  void   ) 
 

Destroy the gnc_string_cache

Definition at line 266 of file gnc-engine-util.c.

00267 {
00268     if (gnc_string_cache)
00269   g_cache_destroy (gnc_string_cache);
00270   gnc_string_cache = NULL;
00271 }

char* gnc_stpcpy (  char *  dest,
const char *  src
) 
 

Local copy of stpcpy, used wtih libc's that don't have one.

Definition at line 177 of file gnc-engine-util.c.

00178 {
00179   strcpy (dest, src);
00180   return (dest + strlen (src));
00181 }

gpointer gnc_string_cache_insert (  gpointer  key  ) 
 

You can use this function with g_hash_table_insert(), or the key (or value), as long as you use the destroy notifier above.

Definition at line 281 of file gnc-engine-util.c.

00282 {
00283   return g_cache_insert(gnc_engine_get_string_cache(), key);
00284 }

void gnc_string_cache_remove (  gconstpointer  key  ) 
 

You can use this function as a destroy notifier for a GHashTable that uses common strings as keys (or values, for that matter.)

Definition at line 274 of file gnc-engine-util.c.

00275 {
00276   g_cache_remove(gnc_engine_get_string_cache(), key);
00277 }

gboolean gnc_strisnum (  const char *  s  ) 
 

Returns true if string s is a number, possibly surrounded by whitespace.

Definition at line 148 of file gnc-engine-util.c.

00149 {
00150   if (s == NULL) return FALSE;
00151   if (*s == 0) return FALSE;
00152 
00153   while (*s && isspace(*s))
00154     s++;
00155 
00156   if (*s == 0) return FALSE;
00157   if (!isdigit(*s)) return FALSE;
00158 
00159   while (*s && isdigit(*s))
00160     s++;
00161 
00162   if (*s == 0) return TRUE;
00163 
00164   while (*s && isspace(*s))
00165     s++;
00166 
00167   if (*s == 0) return TRUE;
00168 
00169   return FALSE;
00170 }

int null_strcmp (  const char *  da,
const char *  db
) 
 

The null_strcmp compares strings a and b the same way that strcmp() does, except that either may be null. This routine assumes that a null string is equal to the empty string.

Definition at line 87 of file gnc-engine-util.c.

00088 {
00089    if (da && db) return strcmp (da, db);
00090    if (!da && db && 0==db[0]) return 0;
00091    if (!db && da && 0==da[0]) return 0;
00092    if (!da && db) return -1;
00093    if (da && !db) return +1;
00094    return 0;
00095 }

void qof_close (  void   ) 
 

Safely close down the Query Object Framework.

Use in place of separate close / shutdown functions (like guid_shutdown(), qof_query_shutdown() etc.) to protect against future changes.

Definition at line 297 of file gnc-engine-util.c.

00298 {
00299         qof_query_shutdown ();
00300         qof_object_shutdown ();
00301         guid_shutdown ();
00302         gnc_engine_string_cache_destroy ();
00303 }

void qof_init (  void   ) 
 

Initialise the Query Object Framework.

Use in place of separate init functions (like guid_init() and qof_query_init() etc.) to protect against future changes.

Definition at line 287 of file gnc-engine-util.c.

00288 {
00289         gnc_engine_get_string_cache ();
00290         guid_init ();
00291         qof_object_initialize ();
00292         qof_query_init ();
00293         qof_book_register ();
00294 }

int qof_util_bool_to_int (  const char *  val  ) 
 

Return integer 1 if the string starts with 't' or 'T' or contains the word 'true' or 'TRUE'; if string is a number, return that number. (Leading whitespace is ignored).

Definition at line 203 of file gnc-engine-util.c.

00204 {
00205         const char * p = qof_util_whitespace_filter (val);
00206         if (!p) return 0;
00207         if ('t' == p[0]) return 1;
00208         if ('T' == p[0]) return 1;
00209         if ('y' == p[0]) return 1;
00210         if ('Y' == p[0]) return 1;
00211         if (strstr (p, "true")) return 1;
00212         if (strstr (p, "TRUE")) return 1;
00213         if (strstr (p, "yes")) return 1;
00214         if (strstr (p, "YES")) return 1;
00215         return atoi (val);
00216 }

const char* qof_util_whitespace_filter (  const char *  val  ) 
 

Return NULL if the field is whitespace (blank, tab, formfeed etc.) Else return pointer to first non-whitespace character.

Definition at line 188 of file gnc-engine-util.c.

00189 {
00190         size_t len;
00191         if (!val) return NULL;
00192 
00193         len = strspn (val, "\a\b\t\n\v\f\r ");
00194         if (0 == val[len]) return NULL;
00195         return val+len;
00196 }

int safe_strcasecmp (  const char *  da,
const char *  db
) 
 

case sensitive comparison of strings da and db - either may be NULL. A non-NULL string is greater than a NULL string.

Parameters:
da string 1.
db string 2.
Returns:
If da == NULL && db != NULL, returns -1. If da != NULL && db == NULL, returns +1. If da != NULL && db != NULL, returns the result of strcmp(da, db). If da == NULL && db == NULL, returns 0.

Definition at line 80 of file gnc-engine-util.c.

00081 {
00082    SAFE_STRCASECMP (da, db);
00083    return 0;
00084 }

int safe_strcmp (  const char *  da,
const char *  db
) 
 

The safe_strcmp compares strings da and db the same way that strcmp() does, except that either may be null. This routine assumes that a non-null string is always greater than a null string.

Parameters:
da string 1.
db string 2.
Returns:
If da == NULL && db != NULL, returns -1. If da != NULL && db == NULL, returns +1. If da != NULL && db != NULL, returns the result of strcmp(da, db). If da == NULL && db == NULL, returns 0.

Definition at line 73 of file gnc-engine-util.c.

00074 {
00075    SAFE_STRCMP (da, db);
00076    return 0;
00077 }

char* strncasestr (  const char *  str1,
const char *  str2,
size_t  len
) 
 

Search for str2 in first nchar chars of str1, ignore case. Return pointer to first match, or null. These are just like that strnstr and the strstr functions, except that they ignore the case.

Definition at line 43 of file gnc-engine-util.c.

00044 {
00045   while (*str1 && len--) 
00046   {
00047     if (toupper(*str1) == toupper(*str2)) 
00048     {
00049       if (strncasecmp(str1,str2,strlen(str2)) == 0) 
00050       {
00051         return (char *) str1;
00052       }
00053     }
00054     str1++;
00055   }
00056   return NULL;
00057 }

char* ultostr (  unsigned long  val,
int  base
) 
 

The ultostr() subroutine is the inverse of strtoul(). It accepts a number and prints it in the indicated base. The returned string should be g_freed when done.

Definition at line 104 of file gnc-engine-util.c.

00105 {
00106   char buf[MAX_DIGITS];
00107   unsigned long broke[MAX_DIGITS];
00108   int i;
00109   unsigned long places=0, reval;
00110   
00111   if ((2>base) || (36<base)) return NULL;
00112 
00113   /* count digits */
00114   places = 0;
00115   for (i=0; i<MAX_DIGITS; i++) {
00116      broke[i] = val;
00117      places ++;
00118      val /= base;
00119      if (0 == val) break;
00120   }
00121 
00122   /* normalize */
00123   reval = 0;
00124   for (i=places-2; i>=0; i--) {
00125     reval += broke[i+1];
00126     reval *= base;
00127     broke[i] -= reval;
00128   }
00129 
00130   /* print */
00131   for (i=0; i<(int)places; i++) {
00132     if (10>broke[i]) {
00133        buf[places-1-i] = 0x30+broke[i];  /* ascii digit zero */
00134     } else {
00135        buf[places-1-i] = 0x41-10+broke[i];  /* ascii capital A */
00136     }
00137   }
00138   buf[places] = 0x0;
00139 
00140   return g_strdup (buf);
00141 }

Generated on Fri Oct 21 15:49:58 2005 for QOF by  doxygen 1.4.5