Prices
[GnuCash Engine: Core, Non-GUI Accounting Functions]

---

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:

commodity: the item being priced.

currency: the denomination of the value of the item being priced.

value: the value of the item being priced.

time: the time the price was valid.

source: a string describing the source of the quote. These strings will be something like this: "Finance::Quote", "user:misc", "user:foo", etc. If the quote came from a user, as a matter of policy, you *must* prefix the string you give with "user:". For now, the only other reserved values are "Finance::Quote" and "old-file-import". Any string used must be added to the source_list array in dialog-price-edit-db.c so that it can be properly translated. (There are unfortunately many strings in users databased, so this string must be translated on output instead of always being used intranslated form.)

type: the type of quote - types possible right now are bid, ask, last, nav, and unknown.

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.

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
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, const char *source)
void	gnc_price_set_typestr (GNCPrice *p, const char *type)
void	gnc_price_set_value (GNCPrice *p, gnc_numeric value)
Getters
GNCPrice *	gnc_price_lookup (const GUID *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)
const char *	gnc_price_get_source (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))
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)
Typedefs
typedef gnc_price_lookup_s	GNCPriceLookup
typedef GList	PriceList

---

Typedef Documentation

typedef struct gnc_price_lookup_s GNCPriceLookup

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

---

Function Documentation

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

{
  /* the clone doesn't belong to a PriceDB */
  GNCPrice *new_p;

  g_return_val_if_fail (book, NULL);

  ENTER ("pr=%p", p);

  if(!p) { LEAVE (" "); return NULL; }

  new_p = gnc_price_create(book);
  if(!new_p) { LEAVE (" "); return NULL; }

  qof_instance_copy_version(new_p, p);

  gnc_price_begin_edit(new_p);
  /* never ever clone guid's */
  gnc_price_set_commodity(new_p, gnc_price_get_commodity(p));
  gnc_price_set_time(new_p, gnc_price_get_time(p));
  gnc_price_set_source(new_p, gnc_price_get_source(p));
  gnc_price_set_typestr(new_p, gnc_price_get_typestr(p));
  gnc_price_set_value(new_p, gnc_price_get_value(p));
  gnc_price_set_currency(new_p, gnc_price_get_currency(p));
  gnc_price_commit_edit(new_p);
  LEAVE (" ");
  return(new_p);
}

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

{
  GNCPrice *p;

  g_return_val_if_fail (book, NULL);

  p = g_object_new(GNC_TYPE_PRICE, NULL);

  p->refcount = 1;
  p->value = gnc_numeric_zero();
  p->type = NULL;
  p->source = NULL;

  qof_instance_init_data (&p->inst, GNC_ID_PRICE, book);
  qof_event_gen (&p->inst, QOF_EVENT_CREATE, NULL);

  return p;
}

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

{
  g_list_foreach(prices, price_list_destroy_helper, NULL);
  g_list_free(prices);
}

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

{
  GList *result_list;
  PriceListIsDuplStruct* pStruct;
  gboolean isDupl;

  if(!prices || !p) return FALSE;
  gnc_price_ref(p);

  if (check_dupl) {
    pStruct = g_new0( PriceListIsDuplStruct, 1 );
    pStruct->pPrice = p;
    pStruct->isDupl = FALSE;
    g_list_foreach( *prices, price_list_is_duplicate, pStruct );
    isDupl = pStruct->isDupl;
    g_free( pStruct );

    if( isDupl ) {
      return TRUE;
    }
  }

  result_list = g_list_insert_sorted(*prices, p, compare_prices_by_date);
  if(!result_list) return FALSE;
  *prices = result_list;
  return TRUE;
}

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

{
  GList *result_list;
  GList *found_element;

  if(!prices || !p) return FALSE;

  found_element = g_list_find(*prices, p);
  if(!found_element) return TRUE;

  result_list = g_list_remove_link(*prices, found_element);
  gnc_price_unref((GNCPrice *) found_element->data);
  g_list_free(found_element);

  *prices = result_list;
  return TRUE;
}

GNCPrice* gnc_price_lookup	(	const GUID *	guid,
		QofBook *	book
	)

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

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

{
  QofCollection *col;

  if (!guid || !book) return NULL;
  col = qof_book_get_collection (book, GNC_ID_PRICE);
  return (GNCPrice *) qof_collection_lookup_entity (col, guid);
}

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

{
  if(!p) return;
  p->refcount++;
}

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

{
  if(!p) return;
  if(p->refcount == 0) {
    return;
  }

  p->refcount--;

  if(p->refcount <= 0) {
    if (NULL != p->db) {
       PERR("last unref while price in database");
    }
    gnc_price_destroy (p);
  }
}

---