Prices

Typedefs
typedef struct gnc_price_lookup_s	GNCPriceLookup
typedef GList	PriceList

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, const char *source)
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)
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))

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

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:

• 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' databases, so this string must be translated on output instead of always being used in untranslated 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.

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

{
    GNCPrice *p;

    g_return_val_if_fail (book, NULL);

    p = g_object_new(GNC_TYPE_PRICE, 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 701 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 645 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 676 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;
}

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

This simple function can be useful for debugging the price code

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

{
    gnc_commodity *commodity;
    gnc_commodity *currency;
    gchar *istr = NULL;           /* indent string */
    const char *str;

    if (!p) return;
    if (!f) return;

    commodity = gnc_price_get_commodity(p);
    currency = gnc_price_get_currency(p);

    if (!commodity) return;
    if (!currency) return;

    istr = g_strnfill(indent, ' ');

    fprintf(f, "%s<pdb:price>\n", istr);
    fprintf(f, "%s  <pdb:commodity pointer=%p>\n", istr, commodity);
    str = gnc_commodity_get_namespace(commodity);
    str = str ? str : "(null)";
    fprintf(f, "%s    <cmdty:ref-space>%s</gnc:cmdty:ref-space>\n", istr, str);
    str = gnc_commodity_get_mnemonic(commodity);
    str = str ? str : "(null)";
    fprintf(f, "%s    <cmdty:ref-id>%s</cmdty:ref-id>\n", istr, str);
    fprintf(f, "%s  </pdb:commodity>\n", istr);
    fprintf(f, "%s  <pdb:currency pointer=%p>\n", istr, currency);
    str = gnc_commodity_get_namespace(currency);
    str = str ? str : "(null)";
    fprintf(f, "%s    <cmdty:ref-space>%s</gnc:cmdty:ref-space>\n", istr, str);
    str = gnc_commodity_get_mnemonic(currency);
    str = str ? str : "(null)";
    fprintf(f, "%s    <cmdty:ref-id>%s</cmdty:ref-id>\n", istr, str);
    fprintf(f, "%s  </pdb:currency>\n", istr);
    str = gnc_price_get_source(p);
    str = str ? str : "(null)";
    fprintf(f, "%s  %s\n", istr, str);
    str = gnc_price_get_typestr(p);
    str = str ? str : "(null)";
    fprintf(f, "%s  %s\n", istr, str);
    fprintf(f, "%s  %g\n", istr, gnc_numeric_to_double(gnc_price_get_value(p)));
    fprintf(f, "%s</pdb:price>\n", istr);

    g_free(istr);
}

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 265 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 272 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);
    }
}

void gnc_pricedb_print_contents	(	GNCPriceDB *	db,
		FILE *	f
	)

This simple function can be useful for debugging the pricedb code

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

{
    if (!db)
    {
        PERR("NULL PriceDB\n");
        return;
    }
    if (!f)
    {
        PERR("NULL FILE*\n");
        return;
    }

    fprintf(f, "<gnc:pricedb>\n");
    gnc_pricedb_foreach_price(db, print_pricedb_adapter, f, FALSE);
    fprintf(f, "</gnc:pricedb>\n");
}