GnuCash  2.6.16
Macros | Typedefs | Enumerations

Macros

#define PRICE_TYPE_LAST   "last"
 
#define PRICE_TYPE_UNK   "unknown"
 
#define PRICE_TYPE_TRN   "transaction"
 

Typedefs

typedef GList PriceList
 

Enumerations

enum  PriceSource {
  PRICE_SOURCE_EDIT_DLG, PRICE_SOURCE_FQ, PRICE_SOURCE_USER_PRICE, PRICE_SOURCE_XFER_DLG_VAL,
  PRICE_SOURCE_SPLIT_REG, PRICE_SOURCE_STOCK_SPLIT, PRICE_SOURCE_INVOICE, PRICE_SOURCE_INVALID
}
 

Constructors

GNCPrice * gnc_price_create (QofBook *book)
 
GNCPrice * gnc_price_clone (GNCPrice *p, QofBook *book)
 

Memory Management

void gnc_price_ref (GNCPrice *p)
 
void gnc_price_unref (GNCPrice *p)
 

Setters

All of the setters store copies of the data given, with the exception of the commodity field which just stores the pointer given. It is assumed that commodities are a global resource and are pointer unique.

Invocations of the setters should be wrapped with calls to gnc_price_begin_edit() and commit_edit(). The begin/commit calls help ensure that the local price db is synchronized with the backend.

void gnc_price_begin_edit (GNCPrice *p)
 
void gnc_price_commit_edit (GNCPrice *p)
 
void gnc_price_set_commodity (GNCPrice *p, gnc_commodity *c)
 
void gnc_price_set_currency (GNCPrice *p, gnc_commodity *c)
 
void gnc_price_set_time (GNCPrice *p, Timespec t)
 
void gnc_price_set_source (GNCPrice *p, PriceSource source)
 
void gnc_price_set_source_string (GNCPrice *p, const char *s)
 
void gnc_price_set_typestr (GNCPrice *p, const char *type)
 
void gnc_price_set_value (GNCPrice *p, gnc_numeric value)
 

Getters

All of the getters return data that's internal to the GNCPrice, not copies, so don't free these values.

GNCPrice * gnc_price_lookup (const GncGUID *guid, QofBook *book)
 
gnc_commodity * gnc_price_get_commodity (const GNCPrice *p)
 
gnc_commodity * gnc_price_get_currency (const GNCPrice *p)
 
Timespec gnc_price_get_time (const GNCPrice *p)
 
PriceSource gnc_price_get_source (const GNCPrice *p)
 
const char * gnc_price_get_source_string (const GNCPrice *p)
 
const char * gnc_price_get_typestr (const GNCPrice *p)
 
gnc_numeric gnc_price_get_value (const GNCPrice *p)
 
gboolean gnc_price_equal (const GNCPrice *p1, const GNCPrice *p2)
 
#define gnc_price_get_guid(X)   qof_entity_get_guid(QOF_INSTANCE(X))
 
#define gnc_price_return_guid(X)   (*(qof_entity_get_guid(QOF_INSTANCE(X))))
 
#define gnc_price_get_book(X)   qof_instance_get_book(QOF_INSTANCE(X))
 

Internal/Debugging

void gnc_price_print (GNCPrice *db, FILE *f, int indent)
 
void gnc_pricedb_print_contents (GNCPriceDB *db, FILE *f)
 

Denominator Constants Price policy: In order to avoid rounding

problems, currency prices (often called exchange rates) are saved in terms of the smaller currency, so that price > 1, with a fixed denominator of 1/1000. Commodity prices in currency are always expressed as value per unit of the commodity with a fixed denominator of the pricing currency's SCU * 10000.

#define CURRENCY_DENOM   10000
 
#define COMMODITY_DENOM_MULT   10000
 

GNCPrice lists

The database communicates multiple prices in and out via gnc price lists. These are just time sorted GLists of GNCPrice pointers. Functions for manipulating these lists are provided. These functions are helpful in that they handle maintaining proper reference counts on behalf of the price list for every price being held in a given list. I.e. insert "refs" the prices being inserted, remove and destroy "unref" the prices that will no longer be referred to by the list.

gboolean gnc_price_list_insert (PriceList **prices, GNCPrice *p, gboolean check_dupl)
 
gboolean gnc_price_list_remove (PriceList **prices, GNCPrice *p)
 
void gnc_price_list_destroy (PriceList *prices)
 
gboolean gnc_price_list_equal (PriceList *prices1, PriceList *prices2)
 

Detailed Description

Each price in the database represents an "instantaneous" quote for a given commodity with respect to another commodity. For example, a given price might represent the value of LNUX in USD on 2001-02-03.

Fields:
Implementation Details:
Note
For source and type, NULL and the empty string are considered the same, so if one of these is "", then after a file save/restore, it might be NULL. Behave accordingly.

GNCPrices are reference counted. When you gnc_price_create one or clone it, the new price's count is set to 1. When you are finished with a price, call gnc_price_unref. If you hand the price pointer to some other code that needs to keep it, make sure it calls gnc_price_ref to indicate its interest in that price, and calls gnc_price_unref when it's finished with the price. For those unfamiliar with reference counting, basically each price stores an integer count which starts at 1 and is incremented every time someone calls gnc_price_ref. Conversely, the count is decremented every time someone calls gnc_price_unref. If the count ever reaches 0, the price is destroyed.

All of the getters return data that's internal to the GNCPrice, not copies, so don't free these values.

All of the setters store copies of the data given, with the exception of the commodity field which just stores the pointer given. It is assumed that commodities are a global resource and are pointer unique.

Enumeration Type Documentation

◆ PriceSource

Price source enum. Be sure to keep in sync with the source_name array in gnc-pricedb.c. These are in preference order, so for example a quote with PRICE_SOURCE_EDIT_DLG will overwrite one with PRICE_SOURCE_FQ but not the other way around.

Definition at line 165 of file gnc-pricedb.h.

166 {
167  PRICE_SOURCE_EDIT_DLG, // "user:price-editor"
168  PRICE_SOURCE_FQ, // "Finance::Quote"
169  PRICE_SOURCE_USER_PRICE, // "user:price"
170  PRICE_SOURCE_XFER_DLG_VAL, // "user:xfer-dialog"
171  PRICE_SOURCE_SPLIT_REG, // "user:split-register"
172  PRICE_SOURCE_STOCK_SPLIT, // "user:stock-split"
173  PRICE_SOURCE_INVOICE, // "user:invoice-post"
174  PRICE_SOURCE_INVALID,
175 } PriceSource;
PriceSource
Definition: gnc-pricedb.h:165

Function Documentation

◆ gnc_price_clone()

GNCPrice* gnc_price_clone ( GNCPrice *  p,
QofBook *  book 
)

gnc_price_clone - returns a newly allocated price that's a content-wise duplicate of the given price, p. The returned clone will have a reference count of 1.

Definition at line 316 of file gnc-pricedb.c.

317 {
318  /* the clone doesn't belong to a PriceDB */
319  GNCPrice *new_p;
320 
321  g_return_val_if_fail (book, NULL);
322 
323  ENTER ("pr=%p", p);
324 
325  if (!p)
326  {
327  LEAVE (" ");
328  return NULL;
329  }
330 
331  new_p = gnc_price_create(book);
332  if (!new_p)
333  {
334  LEAVE (" ");
335  return NULL;
336  }
337 
338  qof_instance_copy_version(new_p, p);
339 
340  gnc_price_begin_edit(new_p);
341  /* never ever clone guid's */
342  gnc_price_set_commodity(new_p, gnc_price_get_commodity(p));
343  gnc_price_set_time(new_p, gnc_price_get_time(p));
344  gnc_price_set_source(new_p, gnc_price_get_source(p));
345  gnc_price_set_typestr(new_p, gnc_price_get_typestr(p));
346  gnc_price_set_value(new_p, gnc_price_get_value(p));
347  gnc_price_set_currency(new_p, gnc_price_get_currency(p));
348  gnc_price_commit_edit(new_p);
349  LEAVE (" ");
350  return(new_p);
351 }
GNCPrice * gnc_price_create(QofBook *book)
Definition: gnc-pricedb.c:258
void qof_instance_copy_version(gpointer to, gconstpointer from)
Definition: qofinstance.c:754
#define ENTER(format, args...)
Definition: qoflog.h:256
#define LEAVE(format, args...)
Definition: qoflog.h:266

◆ gnc_price_create()

GNCPrice* gnc_price_create ( QofBook *  book)

gnc_price_create - returns a newly allocated and initialized price with a reference count of 1.

Definition at line 258 of file gnc-pricedb.c.

259 {
260  GNCPrice *p;
261 
262  g_return_val_if_fail (book, NULL);
263 
264  p = g_object_new(GNC_TYPE_PRICE, NULL);
265 
266  qof_instance_init_data (&p->inst, GNC_ID_PRICE, book);
267  qof_event_gen (&p->inst, QOF_EVENT_CREATE, NULL);
268 
269  return p;
270 }
void qof_instance_init_data(QofInstance *inst, QofIdType type, QofBook *book)
Definition: qofinstance.c:282
void qof_event_gen(QofInstance *entity, QofEventId event_id, gpointer event_data)
Invoke all registered event handlers using the given arguments.
Definition: qofevent.c:230

◆ gnc_price_list_destroy()

void gnc_price_list_destroy ( PriceList *  prices)

gnc_price_list_destroy - destroy the given price list, calling gnc_price_unref on all the prices included in the list.

Definition at line 735 of file gnc-pricedb.c.

736 {
737  g_list_foreach(prices, price_list_destroy_helper, NULL);
738  g_list_free(prices);
739 }

◆ gnc_price_list_insert()

gboolean gnc_price_list_insert ( PriceList **  prices,
GNCPrice *  p,
gboolean  check_dupl 
)

gnc_price_list_insert - insert a price into the given list, calling gnc_price_ref on it during the process.

Definition at line 679 of file gnc-pricedb.c.

680 {
681  GList *result_list;
682  PriceListIsDuplStruct* pStruct;
683  gboolean isDupl;
684 
685  if (!prices || !p) return FALSE;
686  gnc_price_ref(p);
687 
688  if (check_dupl)
689  {
690  pStruct = g_new0( PriceListIsDuplStruct, 1 );
691  pStruct->pPrice = p;
692  pStruct->isDupl = FALSE;
693  g_list_foreach( *prices, price_list_is_duplicate, pStruct );
694  isDupl = pStruct->isDupl;
695  g_free( pStruct );
696 
697  if ( isDupl )
698  {
699  return TRUE;
700  }
701  }
702 
703  result_list = g_list_insert_sorted(*prices, p, compare_prices_by_date);
704  if (!result_list) return FALSE;
705  *prices = result_list;
706  return TRUE;
707 }
void gnc_price_ref(GNCPrice *p)
Definition: gnc-pricedb.c:286

◆ gnc_price_list_remove()

gboolean gnc_price_list_remove ( PriceList **  prices,
GNCPrice *  p 
)

gnc_price_list_remove - remove the price, p, from the given list, calling gnc_price_unref on it during the process.

Definition at line 710 of file gnc-pricedb.c.

711 {
712  GList *result_list;
713  GList *found_element;
714 
715  if (!prices || !p) return FALSE;
716 
717  found_element = g_list_find(*prices, p);
718  if (!found_element) return TRUE;
719 
720  result_list = g_list_remove_link(*prices, found_element);
721  gnc_price_unref((GNCPrice *) found_element->data);
722  g_list_free(found_element);
723 
724  *prices = result_list;
725  return TRUE;
726 }
void gnc_price_unref(GNCPrice *p)
Definition: gnc-pricedb.c:293

◆ gnc_price_print()

void gnc_price_print ( GNCPrice *  db,
FILE *  f,
int  indent 
)

This simple function can be useful for debugging the price code

Definition at line 2339 of file gnc-pricedb.c.

2340 {
2341  gnc_commodity *commodity;
2342  gnc_commodity *currency;
2343  gchar *istr = NULL; /* indent string */
2344  const char *str;
2345 
2346  if (!p) return;
2347  if (!f) return;
2348 
2349  commodity = gnc_price_get_commodity(p);
2350  currency = gnc_price_get_currency(p);
2351 
2352  if (!commodity) return;
2353  if (!currency) return;
2354 
2355  istr = g_strnfill(indent, ' ');
2356 
2357  fprintf(f, "%s<pdb:price>\n", istr);
2358  fprintf(f, "%s <pdb:commodity pointer=%p>\n", istr, commodity);
2359  str = gnc_commodity_get_namespace(commodity);
2360  str = str ? str : "(null)";
2361  fprintf(f, "%s <cmdty:ref-space>%s</gnc:cmdty:ref-space>\n", istr, str);
2362  str = gnc_commodity_get_mnemonic(commodity);
2363  str = str ? str : "(null)";
2364  fprintf(f, "%s <cmdty:ref-id>%s</cmdty:ref-id>\n", istr, str);
2365  fprintf(f, "%s </pdb:commodity>\n", istr);
2366  fprintf(f, "%s <pdb:currency pointer=%p>\n", istr, currency);
2367  str = gnc_commodity_get_namespace(currency);
2368  str = str ? str : "(null)";
2369  fprintf(f, "%s <cmdty:ref-space>%s</gnc:cmdty:ref-space>\n", istr, str);
2370  str = gnc_commodity_get_mnemonic(currency);
2371  str = str ? str : "(null)";
2372  fprintf(f, "%s <cmdty:ref-id>%s</cmdty:ref-id>\n", istr, str);
2373  fprintf(f, "%s </pdb:currency>\n", istr);
2374  str = source_names[gnc_price_get_source(p)];
2375  str = str ? str : "invalid";
2376  fprintf(f, "%s %s\n", istr, str);
2377  str = gnc_price_get_typestr(p);
2378  str = str ? str : "(null)";
2379  fprintf(f, "%s %s\n", istr, str);
2380  fprintf(f, "%s %g\n", istr, gnc_numeric_to_double(gnc_price_get_value(p)));
2381  fprintf(f, "%s</pdb:price>\n", istr);
2382 
2383  g_free(istr);
2384 }
const char * gnc_commodity_get_mnemonic(const gnc_commodity *cm)
const char * gnc_commodity_get_namespace(const gnc_commodity *cm)
double gnc_numeric_to_double(gnc_numeric in)
Definition: gnc-numeric.c:1255

◆ gnc_price_ref()

void gnc_price_ref ( GNCPrice *  p)

gnc_price_ref - indicate your need for a given price to stick around (i.e. increase its reference count by 1).

Definition at line 286 of file gnc-pricedb.c.

287 {
288  if (!p) return;
289  p->refcount++;
290 }

◆ gnc_price_unref()

void gnc_price_unref ( GNCPrice *  p)

gnc_price_unref - indicate you're finished with a price (i.e. decrease its reference count by 1).

Definition at line 293 of file gnc-pricedb.c.

294 {
295  if (!p) return;
296  if (p->refcount == 0)
297  {
298  return;
299  }
300 
301  p->refcount--;
302 
303  if (p->refcount <= 0)
304  {
305  if (NULL != p->db)
306  {
307  PERR("last unref while price in database");
308  }
309  gnc_price_destroy (p);
310  }
311 }
#define PERR(format, args...)
Definition: qoflog.h:232

◆ gnc_pricedb_print_contents()

void gnc_pricedb_print_contents ( GNCPriceDB *  db,
FILE *  f 
)

This simple function can be useful for debugging the pricedb code

Definition at line 2395 of file gnc-pricedb.c.

2396 {
2397  if (!db)
2398  {
2399  PERR("NULL PriceDB\n");
2400  return;
2401  }
2402  if (!f)
2403  {
2404  PERR("NULL FILE*\n");
2405  return;
2406  }
2407 
2408  fprintf(f, "<gnc:pricedb>\n");
2409  gnc_pricedb_foreach_price(db, print_pricedb_adapter, f, FALSE);
2410  fprintf(f, "</gnc:pricedb>\n");
2411 }
#define PERR(format, args...)
Definition: qoflog.h:232
gboolean gnc_pricedb_foreach_price(GNCPriceDB *db, gboolean(*f)(GNCPrice *p, gpointer user_data), gpointer user_data, gboolean stable_order)
Definition: gnc-pricedb.c:2259