GnuCash  4.12-5-ga27adb78e3+
Macros | Typedefs | Enumerations

Each price in the database represents an "instantaneous" quote for a given commodity with respect to another commodity. More...

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_SPLIT_IMPORT, PRICE_SOURCE_STOCK_SPLIT, PRICE_SOURCE_STOCK_TRANSACTION,
  PRICE_SOURCE_INVOICE, PRICE_SOURCE_TEMP, PRICE_SOURCE_INVALID
}
 Price source enum. More...
 

Constructors

GNCPrice * gnc_price_create (QofBook *book)
 gnc_price_create - returns a newly allocated and initialized price with a reference count of 1. More...
 
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. More...
 
GNCPrice * gnc_price_invert (GNCPrice *p)
 Return a newly-allocated price that's the inverse of the given price, p. More...
 

Memory Management

void gnc_price_ref (GNCPrice *p)
 gnc_price_ref - indicate your need for a given price to stick around (i.e. More...
 
void gnc_price_unref (GNCPrice *p)
 gnc_price_unref - indicate you're finished with a price (i.e. More...
 

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_time64 (GNCPrice *p, time64 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)
 
time64 gnc_price_get_time64 (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)
 This simple function can be useful for debugging the price code.
 
void gnc_pricedb_print_contents (GNCPriceDB *db, FILE *f)
 This simple function can be useful for debugging the pricedb code.
 

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)
 gnc_price_list_insert - insert a price into the given list, calling gnc_price_ref on it during the process. More...
 
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. More...
 
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. More...
 
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 169 of file gnc-pricedb.h.

170 {
171  PRICE_SOURCE_EDIT_DLG, // "user:price-editor"
172  PRICE_SOURCE_FQ, // "Finance::Quote"
173  PRICE_SOURCE_USER_PRICE, // "user:price"
174  PRICE_SOURCE_XFER_DLG_VAL, // "user:xfer-dialog"
175  PRICE_SOURCE_SPLIT_REG, // "user:split-register"
176  PRICE_SOURCE_SPLIT_IMPORT, // "user:split-import"
177  PRICE_SOURCE_STOCK_SPLIT, // "user:stock-split"
178  PRICE_SOURCE_STOCK_TRANSACTION,// "user:stock-transaction"
179  PRICE_SOURCE_INVOICE, // "user:invoice-post"
180  PRICE_SOURCE_TEMP, // "temporary"
181  PRICE_SOURCE_INVALID, // "invalid"
182 } PriceSource;
PriceSource
Price source enum.
Definition: gnc-pricedb.h:169

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 367 of file gnc-pricedb.c.

368 {
369  /* the clone doesn't belong to a PriceDB */
370  GNCPrice *new_p;
371 
372  g_return_val_if_fail (book, NULL);
373 
374  ENTER ("pr=%p", p);
375 
376  if (!p)
377  {
378  LEAVE ("return NULL");
379  return NULL;
380  }
381 
382  new_p = gnc_price_create(book);
383  if (!new_p)
384  {
385  LEAVE ("return NULL");
386  return NULL;
387  }
388 
389  qof_instance_copy_version(new_p, p);
390 
391  gnc_price_begin_edit(new_p);
392  /* never ever clone guid's */
393  gnc_price_set_commodity(new_p, gnc_price_get_commodity(p));
394  gnc_price_set_time64(new_p, gnc_price_get_time64(p));
395  gnc_price_set_source(new_p, gnc_price_get_source(p));
396  gnc_price_set_typestr(new_p, gnc_price_get_typestr(p));
397  gnc_price_set_value(new_p, gnc_price_get_value(p));
398  gnc_price_set_currency(new_p, gnc_price_get_currency(p));
399  gnc_price_commit_edit(new_p);
400  LEAVE ("return cloned price %p", new_p);
401  return(new_p);
402 }
GNCPrice * gnc_price_create(QofBook *book)
gnc_price_create - returns a newly allocated and initialized price with a reference count of 1...
Definition: gnc-pricedb.c:308
#define ENTER(format, args...)
Print a function entry debugging message.
Definition: qoflog.h:272
#define LEAVE(format, args...)
Print a function exit debugging message.
Definition: qoflog.h:282

◆ 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 308 of file gnc-pricedb.c.

309 {
310  GNCPrice *p;
311 
312  g_return_val_if_fail (book, NULL);
313 
314  ENTER(" ");
315  p = g_object_new(GNC_TYPE_PRICE, NULL);
316 
317  qof_instance_init_data (&p->inst, GNC_ID_PRICE, book);
318  qof_event_gen (&p->inst, QOF_EVENT_CREATE, NULL);
319  LEAVE ("price created %p", p);
320  return p;
321 }
#define ENTER(format, args...)
Print a function entry debugging message.
Definition: qoflog.h:272
void qof_instance_init_data(QofInstance *inst, QofIdType type, QofBook *book)
Initialise the settings associated with an instance.
#define LEAVE(format, args...)
Print a function exit debugging message.
Definition: qoflog.h:282
void qof_event_gen(QofInstance *entity, QofEventId event_id, gpointer event_data)
Invoke all registered event handlers using the given arguments.
Definition: qofevent.cpp:231

◆ gnc_price_invert()

GNCPrice* gnc_price_invert ( GNCPrice *  p)

Return a newly-allocated price that's the inverse of the given price, p.

Inverse means that the commodity and currency are swapped and the value is the numeric inverse of the original's. The source is set to PRICE_SOURCE_TEMP to prevent it being saved in the pricedb.

Parameters
pThe price to invert
Returns
a new price, with a ref-count of 1. Don't forget to unref it!

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

406 {
407  QofBook *book = qof_instance_get_book (QOF_INSTANCE(p));
408  GNCPrice *new_p = gnc_price_create (book);
409  qof_instance_copy_version(new_p, p);
410  gnc_price_begin_edit(new_p);
411  gnc_price_set_time64(new_p, gnc_price_get_time64(p));
412  gnc_price_set_source(new_p, PRICE_SOURCE_TEMP);
413  gnc_price_set_typestr(new_p, gnc_price_get_typestr(p));
414  gnc_price_set_commodity(new_p, gnc_price_get_currency(p));
415  gnc_price_set_currency(new_p, gnc_price_get_commodity(p));
416  gnc_price_set_value(new_p, gnc_numeric_invert(gnc_price_get_value(p)));
417  gnc_price_commit_edit(new_p);
418  return new_p;
419 }
GNCPrice * gnc_price_create(QofBook *book)
gnc_price_create - returns a newly allocated and initialized price with a reference count of 1...
Definition: gnc-pricedb.c:308
QofBook * qof_instance_get_book(gconstpointer inst)
Return the book pointer.
gnc_numeric gnc_numeric_invert(gnc_numeric num)
Invert a gnc_numeric.

◆ 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 791 of file gnc-pricedb.c.

792 {
793  g_list_foreach(prices, price_list_destroy_helper, NULL);
794  g_list_free(prices);
795 }

◆ 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 735 of file gnc-pricedb.c.

736 {
737  GList *result_list;
738  PriceListIsDuplStruct* pStruct;
739  gboolean isDupl;
740 
741  if (!prices || !p) return FALSE;
742  gnc_price_ref(p);
743 
744  if (check_dupl)
745  {
746  pStruct = g_new0( PriceListIsDuplStruct, 1 );
747  pStruct->pPrice = p;
748  pStruct->isDupl = FALSE;
749  g_list_foreach( *prices, price_list_is_duplicate, pStruct );
750  isDupl = pStruct->isDupl;
751  g_free( pStruct );
752 
753  if ( isDupl )
754  {
755  return TRUE;
756  }
757  }
758 
759  result_list = g_list_insert_sorted(*prices, p, compare_prices_by_date);
760  if (!result_list) return FALSE;
761  *prices = result_list;
762  return TRUE;
763 }
void gnc_price_ref(GNCPrice *p)
gnc_price_ref - indicate your need for a given price to stick around (i.e.
Definition: gnc-pricedb.c:337

◆ 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 766 of file gnc-pricedb.c.

767 {
768  GList *result_list;
769  GList *found_element;
770 
771  if (!prices || !p) return FALSE;
772 
773  found_element = g_list_find(*prices, p);
774  if (!found_element) return TRUE;
775 
776  result_list = g_list_remove_link(*prices, found_element);
777  gnc_price_unref((GNCPrice *) found_element->data);
778  g_list_free(found_element);
779 
780  *prices = result_list;
781  return TRUE;
782 }
void gnc_price_unref(GNCPrice *p)
gnc_price_unref - indicate you're finished with a price (i.e.
Definition: gnc-pricedb.c:344

◆ 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 337 of file gnc-pricedb.c.

338 {
339  if (!p) return;
340  p->refcount++;
341 }

◆ 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 344 of file gnc-pricedb.c.

345 {
346  if (!p) return;
347  if (p->refcount == 0)
348  {
349  return;
350  }
351 
352  p->refcount--;
353 
354  if (p->refcount <= 0)
355  {
356  if (NULL != p->db)
357  {
358  PERR("last unref while price in database");
359  }
360  gnc_price_destroy (p);
361  }
362 }
#define PERR(format, args...)
Log a serious error.
Definition: qoflog.h:244