GnuCash  4.6-313-gb6cbc9786+
gnc-pricedb.h
Go to the documentation of this file.
1 /********************************************************************
2  * gnc-pricedb.h -- a simple price database for gnucash. *
3  * *
4  * This program is free software; you can redistribute it and/or *
5  * modify it under the terms of the GNU General Public License as *
6  * published by the Free Software Foundation; either version 2 of *
7  * the License, or (at your option) any later version. *
8  * *
9  * This program is distributed in the hope that it will be useful, *
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of *
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
12  * GNU General Public License for more details. *
13  * *
14  * You should have received a copy of the GNU General Public License*
15  * along with this program; if not, contact: *
16  * *
17  * Free Software Foundation Voice: +1-617-542-5942 *
18  * 51 Franklin Street, Fifth Floor Fax: +1-617-542-2652 *
19  * Boston, MA 02110-1301, USA gnu@gnu.org *
20  * *
21  *******************************************************************/
22 
23 #ifndef GNC_PRICEDB_H
24 #define GNC_PRICEDB_H
25 
26 typedef struct _GncPriceClass GNCPriceClass;
27 typedef struct _GncPriceDBClass GNCPriceDBClass;
28 
29 #include <stdio.h>
30 #include "qof.h"
31 #include "gnc-commodity.h"
32 #include "gnc-engine.h"
33 
34 #ifdef __cplusplus
35 extern "C" {
36 #endif
37 
38 /* --- type macros --- */
39 #define GNC_TYPE_PRICE (gnc_price_get_type ())
40 #define GNC_PRICE(o) \
41  (G_TYPE_CHECK_INSTANCE_CAST ((o), GNC_TYPE_PRICE, GNCPrice))
42 #define GNC_PRICE_CLASS(k) \
43  (G_TYPE_CHECK_CLASS_CAST((k), GNC_TYPE_PRICE, GNCPriceClass))
44 #define GNC_IS_PRICE(o) \
45  (G_TYPE_CHECK_INSTANCE_TYPE ((o), GNC_TYPE_PRICE))
46 #define GNC_IS_PRICE_CLASS(k) \
47  (G_TYPE_CHECK_CLASS_TYPE ((k), GNC_TYPE_PRICE))
48 #define GNC_PRICE_GET_CLASS(o) \
49  (G_TYPE_INSTANCE_GET_CLASS ((o), GNC_TYPE_PRICE, GNCPriceClass))
50 GType gnc_price_get_type(void);
51 
52 /* --- type macros --- */
53 #define GNC_TYPE_PRICEDB (gnc_pricedb_get_type ())
54 #define GNC_PRICEDB(o) \
55  (G_TYPE_CHECK_INSTANCE_CAST ((o), GNC_TYPE_PRICEDB, GNCPriceDB))
56 #define GNC_PRICEDB_CLASS(k) \
57  (G_TYPE_CHECK_CLASS_CAST((k), GNC_TYPE_PRICEDB, GNCPriceDBClass))
58 #define GNC_IS_PRICEDB(o) \
59  (G_TYPE_CHECK_INSTANCE_TYPE ((o), GNC_TYPE_PRICEDB))
60 #define GNC_IS_PRICEDB_CLASS(k) \
61  (G_TYPE_CHECK_CLASS_TYPE ((k), GNC_TYPE_PRICEDB))
62 #define GNC_PRICEDB_GET_CLASS(o) \
63  (G_TYPE_INSTANCE_GET_CLASS ((o), GNC_TYPE_PRICEDB, GNCPriceDBClass))
64 GType gnc_pricedb_get_type(void);
65 
66 
156 /* ================================================================ */
157 
162 typedef GList PriceList;
163 
169 typedef enum
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_INVOICE, // "user:invoice-post"
179  PRICE_SOURCE_TEMP, // "temporary"
180  PRICE_SOURCE_INVALID, // "invalid"
181 } PriceSource;
182 
183 #define PRICE_TYPE_LAST "last"
184 #define PRICE_TYPE_UNK "unknown"
185 #define PRICE_TYPE_TRN "transaction"
186 /* ------------------ */
192 /*@ dependent @*/
193 GNCPrice *gnc_price_create(QofBook *book);
194 
198 GNCPrice *gnc_price_clone(GNCPrice* p, QofBook *book);
199 
208 GNCPrice *gnc_price_invert(GNCPrice *p);
209 
212 /* ------------------ */
218 void gnc_price_ref(GNCPrice *p);
219 
222 void gnc_price_unref(GNCPrice *p);
225 /* ------------------ */
237 void gnc_price_begin_edit (GNCPrice *p);
238 void gnc_price_commit_edit (GNCPrice *p);
239 
240 void gnc_price_set_commodity(GNCPrice *p, gnc_commodity *c);
241 void gnc_price_set_currency(GNCPrice *p, gnc_commodity *c);
242 void gnc_price_set_time64(GNCPrice *p, time64 t);
243 void gnc_price_set_source(GNCPrice *p, PriceSource source);
244 void gnc_price_set_source_string(GNCPrice *p, const char* s);
245 void gnc_price_set_typestr(GNCPrice *p, const char* type);
246 void gnc_price_set_value(GNCPrice *p, gnc_numeric value);
249 /* ------------------ */
255  GNCPrice * gnc_price_lookup (const GncGUID *guid, QofBook *book);
256 /*@ dependent @*/
257 gnc_commodity * gnc_price_get_commodity(const GNCPrice *p);
258 /*@ dependent @*/
259 gnc_commodity * gnc_price_get_currency(const GNCPrice *p);
260 time64 gnc_price_get_time64(const GNCPrice *p);
261 PriceSource gnc_price_get_source(const GNCPrice *p);
262 const char * gnc_price_get_source_string(const GNCPrice *p);
263 const char * gnc_price_get_typestr(const GNCPrice *p);
264 gnc_numeric gnc_price_get_value(const GNCPrice *p);
265 gboolean gnc_price_equal(const GNCPrice *p1, const GNCPrice *p2);
266 
267 #define gnc_price_get_guid(X) qof_entity_get_guid(QOF_INSTANCE(X))
268 #define gnc_price_return_guid(X) (*(qof_entity_get_guid(QOF_INSTANCE(X))))
269 #define gnc_price_get_book(X) qof_instance_get_book(QOF_INSTANCE(X))
270 
275 void gnc_price_print(GNCPrice *db, FILE *f, int indent);
284 #define CURRENCY_DENOM 10000
285 #define COMMODITY_DENOM_MULT 10000
286 
287 /* ================================================================ */
302 gboolean gnc_price_list_insert(PriceList **prices, GNCPrice *p,
303  gboolean check_dupl);
304 
307 gboolean gnc_price_list_remove(PriceList **prices, GNCPrice *p);
308 
311 void gnc_price_list_destroy(PriceList *prices);
312 
313 gboolean gnc_price_list_equal(PriceList *prices1, PriceList *prices2);
317 /* ================================================================ */
330 typedef struct gnc_price_db_s GNCPriceDB;
331 
336 GNCPriceDB * gnc_pricedb_get_db(QofBook *book);
341 GNCPriceDB * gnc_collection_get_pricedb(QofCollection *col);
342 
349 void gnc_pricedb_destroy(GNCPriceDB *db);
350 
352 void gnc_pricedb_begin_edit (GNCPriceDB *);
354 void gnc_pricedb_commit_edit (GNCPriceDB *);
355 
362 void gnc_pricedb_set_bulk_update(GNCPriceDB *db, gboolean bulk_update);
363 
372 gboolean gnc_pricedb_add_price(GNCPriceDB *db, GNCPrice *p);
373 
378 gboolean gnc_pricedb_remove_price(GNCPriceDB *db, GNCPrice *p);
379 
380 typedef enum
381 {
382  PRICE_REMOVE_SOURCE_FQ = 1, // this flag is set when added by F:Q checked
383  PRICE_REMOVE_SOURCE_USER = 2, // this flag is set when added by the user checked
384  PRICE_REMOVE_SOURCE_APP = 4, // this flag is set when added by the app checked
385  PRICE_REMOVE_SOURCE_COMM = 8, // this flag is set when we have commodities selected
386 } PriceRemoveSourceFlags;
387 
388 typedef enum
389 {
390  PRICE_REMOVE_KEEP_NONE, // keep none
391  PRICE_REMOVE_KEEP_LAST_WEEKLY, // leave last one of every week
392  PRICE_REMOVE_KEEP_LAST_MONTHLY, // leave last one of every month
393  PRICE_REMOVE_KEEP_LAST_QUARTERLY, // leave last one of every quarter
394  PRICE_REMOVE_KEEP_LAST_PERIOD, // leave last one of every annual period
395  PRICE_REMOVE_KEEP_SCALED, // leave one every week then one a month
396 } PriceRemoveKeepOptions;
397 
407 gboolean gnc_pricedb_remove_old_prices(GNCPriceDB *db, GList *comm_list,
408  GDate *fiscal_end_date, time64 cutoff,
409  PriceRemoveSourceFlags source,
410  PriceRemoveKeepOptions keep);
411 
421 GNCPrice * gnc_pricedb_lookup_latest(GNCPriceDB *db,
422  const gnc_commodity *commodity,
423  const gnc_commodity *currency);
424 
434 PriceList * gnc_pricedb_lookup_latest_any_currency(GNCPriceDB *db,
435  const gnc_commodity *commodity);
436 
447 gboolean gnc_pricedb_has_prices(GNCPriceDB *db,
448  const gnc_commodity *commodity,
449  const gnc_commodity *currency);
450 
461 PriceList * gnc_pricedb_get_prices(GNCPriceDB *db,
462  const gnc_commodity *commodity,
463  const gnc_commodity *currency);
464 
475 /* NOT USED */
476 GNCPrice * gnc_pricedb_lookup_at_time64(GNCPriceDB *db,
477  const gnc_commodity *commodity,
478  const gnc_commodity *currency,
479  time64 t);
480 
493 GNCPrice * gnc_pricedb_lookup_day_t64(GNCPriceDB *db,
494  const gnc_commodity *commodity,
495  const gnc_commodity *currency,
496  time64 t);
497 
509 GNCPrice * gnc_pricedb_lookup_nearest_in_time64(GNCPriceDB *db,
510  const gnc_commodity *c,
511  const gnc_commodity *currency,
512  time64 t);
513 
526 PriceList * gnc_pricedb_lookup_nearest_in_time_any_currency_t64(GNCPriceDB *db,
527  const gnc_commodity *c,
528  time64 t);
529 
541 GNCPrice * gnc_pricedb_lookup_nearest_before_t64 (GNCPriceDB *db,
542  const gnc_commodity *c,
543  const gnc_commodity *currency,
544  time64 t);
545 
556 PriceList * gnc_pricedb_lookup_nearest_before_any_currency_t64 (GNCPriceDB *db,
557  const gnc_commodity *c,
558  time64 t);
559 
569 gnc_numeric gnc_pricedb_get_nearest_before_price (GNCPriceDB *pdb,
570  const gnc_commodity *orig_currency,
571  const gnc_commodity *new_currency,
572  const time64 t);
573 
583 gnc_numeric gnc_pricedb_get_nearest_price (GNCPriceDB *pdb,
584  const gnc_commodity *orig_currency,
585  const gnc_commodity *new_currency,
586  const time64 t);
587 
595 gnc_numeric gnc_pricedb_get_latest_price (GNCPriceDB *pdb,
596  const gnc_commodity *orig_currency,
597  const gnc_commodity *new_currency);
598 
599 
609 gnc_numeric
611  gnc_numeric balance,
612  const gnc_commodity *balance_currency,
613  const gnc_commodity *new_currency);
614 
625 gnc_numeric
627  gnc_numeric balance,
628  const gnc_commodity *balance_currency,
629  const gnc_commodity *new_currency,
630  time64 t);
631 
642 gnc_numeric
644  gnc_numeric balance,
645  const gnc_commodity *balance_currency,
646  const gnc_commodity *new_currency,
647  time64 t);
648 
649 typedef gboolean (*GncPriceForeachFunc)(GNCPrice *p, gpointer user_data);
650 
665 gboolean gnc_pricedb_foreach_price(GNCPriceDB *db,
666  GncPriceForeachFunc f,
667  gpointer user_data,
668  gboolean stable_order);
669 
675 int
676 gnc_pricedb_num_prices(GNCPriceDB *db,
677  const gnc_commodity *c);
678 
686 GNCPrice *
687 gnc_pricedb_nth_price (GNCPriceDB *db,
688  const gnc_commodity *c,
689  const int n);
690 
691 void gnc_pricedb_nth_price_reset_cache (GNCPriceDB *db);
692 
693 /* The following two convenience functions are used to test the xml backend */
698 guint gnc_pricedb_get_num_prices(GNCPriceDB *db);
699 
703 gboolean gnc_pricedb_equal (GNCPriceDB *db1, GNCPriceDB *db2);
704 
708 void gnc_pricedb_print_contents(GNCPriceDB *db, FILE *f);
715 #define PRICE_COMMODITY "price-commodity"
716 #define PRICE_CURRENCY "price-currency"
717 #define PRICE_DATE "price-date"
718 #define PRICE_SOURCE "price-source"
719 #define PRICE_TYPE "price-type"
720 #define PRICE_VALUE "price-value"
721 
725 #ifdef __cplusplus
726 } /* extern "C" */
727 #endif
728 
729 #endif /* GNC_PRICEDB_H */
730 
void gnc_price_list_destroy(PriceList *prices)
gnc_price_list_destroy - destroy the given price list, calling gnc_price_unref on all the prices incl...
Definition: gnc-pricedb.c:790
GNCPrice * gnc_pricedb_lookup_day_t64(GNCPriceDB *db, const gnc_commodity *commodity, const gnc_commodity *currency, time64 t)
Return the price between the two commodities on the indicated day.
Definition: gnc-pricedb.c:2233
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:307
GNCPrice * gnc_pricedb_nth_price(GNCPriceDB *db, const gnc_commodity *c, const int n)
Get the nth price for the given commodity in reverse date order.
Definition: gnc-pricedb.c:2181
void gnc_pricedb_print_contents(GNCPriceDB *db, FILE *f)
This simple function can be useful for debugging the pricedb code.
Definition: gnc-pricedb.c:3006
GNCPrice * gnc_pricedb_lookup_at_time64(GNCPriceDB *db, const gnc_commodity *commodity, const gnc_commodity *currency, time64 t)
Find the price between two commodities at a time64.
Definition: gnc-pricedb.c:2242
GNCPrice * gnc_price_invert(GNCPrice *p)
Return a newly-allocated price that&#39;s the inverse of the given price, p.
Definition: gnc-pricedb.c:404
int gnc_pricedb_num_prices(GNCPriceDB *db, const gnc_commodity *c)
Get the number of prices, in any currency, for a given commodity.
Definition: gnc-pricedb.c:2135
void gnc_price_unref(GNCPrice *p)
gnc_price_unref - indicate you&#39;re finished with a price (i.e.
Definition: gnc-pricedb.c:343
gboolean gnc_pricedb_add_price(GNCPriceDB *db, GNCPrice *p)
Add a price to the pricedb.
Definition: gnc-pricedb.c:1165
GNCPriceDB * gnc_collection_get_pricedb(QofCollection *col)
Return the pricedb via the Book&#39;s collection.
Definition: gnc-pricedb.c:955
gboolean gnc_pricedb_equal(GNCPriceDB *db1, GNCPriceDB *db2)
Test equality of two pricedbs.
Definition: gnc-pricedb.c:1039
gnc_numeric gnc_pricedb_get_nearest_price(GNCPriceDB *pdb, const gnc_commodity *orig_currency, const gnc_commodity *new_currency, const time64 t)
Retrieve the price one currency to another using the price nearest to the given time.
Definition: gnc-pricedb.c:2610
gboolean gnc_pricedb_remove_old_prices(GNCPriceDB *db, GList *comm_list, GDate *fiscal_end_date, time64 cutoff, PriceRemoveSourceFlags source, PriceRemoveKeepOptions keep)
Remove and unref prices older than a certain time.
Definition: gnc-pricedb.c:1601
gnc_numeric gnc_pricedb_get_latest_price(GNCPriceDB *pdb, const gnc_commodity *orig_currency, const gnc_commodity *new_currency)
Retrieve the price one currency to another using the latest price.
Definition: gnc-pricedb.c:2619
Data type.
Definition: gnc-pricedb-p.h:55
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 pr...
Definition: gnc-pricedb.c:734
gnc_numeric gnc_pricedb_convert_balance_nearest_before_price_t64(GNCPriceDB *pdb, gnc_numeric balance, const gnc_commodity *balance_currency, const gnc_commodity *new_currency, time64 t)
Convert a balance from one currency to another using the price nearest to before the given time...
Definition: gnc-pricedb.c:2675
GNCPriceDB * gnc_pricedb_get_db(QofBook *book)
Return the pricedb associated with the book.
Definition: gnc-pricedb.c:962
gnc_numeric gnc_pricedb_convert_balance_latest_price(GNCPriceDB *pdb, gnc_numeric balance, const gnc_commodity *balance_currency, const gnc_commodity *new_currency)
Convert a balance from one currency to another using the most recent price between the two...
Definition: gnc-pricedb.c:2654
void gnc_pricedb_destroy(GNCPriceDB *db)
Destroy the given pricedb and unref all of the prices it contains.
Definition: gnc-pricedb.c:918
guint gnc_pricedb_get_num_prices(GNCPriceDB *db)
Return the number of prices in the database.
Definition: gnc-pricedb.c:984
void gnc_price_print(GNCPrice *db, FILE *f, int indent)
This simple function can be useful for debugging the price code.
Definition: gnc-pricedb.c:2950
gnc_numeric gnc_pricedb_get_nearest_before_price(GNCPriceDB *pdb, const gnc_commodity *orig_currency, const gnc_commodity *new_currency, const time64 t)
Retrieve the price one currency to another using the price nearest to before the given time...
Definition: gnc-pricedb.c:2601
PriceList * gnc_pricedb_lookup_nearest_in_time_any_currency_t64(GNCPriceDB *db, const gnc_commodity *c, time64 t)
Return the price nearest in time to that given between the given commodity and every other...
Definition: gnc-pricedb.c:2020
void gnc_pricedb_begin_edit(GNCPriceDB *)
Begin an edit.
Definition: gnc-pricedb.c:446
PriceList * gnc_pricedb_lookup_latest_any_currency(GNCPriceDB *db, const gnc_commodity *commodity)
Find the most recent price between a commodity and all other commodities.
Definition: gnc-pricedb.c:2012
All type declarations for the whole Gnucash engine.
gboolean gnc_pricedb_remove_price(GNCPriceDB *db, GNCPrice *p)
Remove a price from the pricedb and unref the price.
Definition: gnc-pricedb.c:1272
GNCPrice * gnc_pricedb_lookup_nearest_in_time64(GNCPriceDB *db, const gnc_commodity *c, const gnc_commodity *currency, time64 t)
Return the price between the two commoditiesz nearest to the given time.
Definition: gnc-pricedb.c:2386
gboolean gnc_pricedb_has_prices(GNCPriceDB *db, const gnc_commodity *commodity, const gnc_commodity *currency)
Report whether the pricedb contains prices for one commodity in another.
Definition: gnc-pricedb.c:2065
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 durin...
Definition: gnc-pricedb.c:765
GNCPrice * gnc_price_clone(GNCPrice *p, QofBook *book)
gnc_price_clone - returns a newly allocated price that&#39;s a content-wise duplicate of the given price...
Definition: gnc-pricedb.c:366
gnc_numeric gnc_pricedb_convert_balance_nearest_price_t64(GNCPriceDB *pdb, gnc_numeric balance, const gnc_commodity *balance_currency, const gnc_commodity *new_currency, time64 t)
Convert a balance from one currency to another using the price nearest to the given time...
Definition: gnc-pricedb.c:2664
PriceSource
Price source enum.
Definition: gnc-pricedb.h:169
void gnc_pricedb_set_bulk_update(GNCPriceDB *db, gboolean bulk_update)
Set flag to indicate whether duplication checks should be performed.
Definition: gnc-pricedb.c:934
gint64 time64
Many systems, including Microsoft Windows and BSD-derived Unixes like Darwin, are retaining the int-3...
Definition: gnc-date.h:93
gboolean gnc_pricedb_foreach_price(GNCPriceDB *db, GncPriceForeachFunc f, gpointer user_data, gboolean stable_order)
Call a GncPriceForeachFunction once for each price in db, until the function returns FALSE...
Definition: gnc-pricedb.c:2870
GNCPrice * gnc_pricedb_lookup_latest(GNCPriceDB *db, const gnc_commodity *commodity, const gnc_commodity *currency)
Find the most recent price between the two commodities.
Definition: gnc-pricedb.c:1787
PriceList * gnc_pricedb_lookup_nearest_before_any_currency_t64(GNCPriceDB *db, const gnc_commodity *c, time64 t)
Return the nearest price between the given commodity and any other before the given time...
Definition: gnc-pricedb.c:2040
The type used to store guids in C.
Definition: guid.h:75
GNCPrice * gnc_pricedb_lookup_nearest_before_t64(GNCPriceDB *db, const gnc_commodity *c, const gnc_commodity *currency, time64 t)
Return the nearest price between the given commodities before the given time.
Definition: gnc-pricedb.c:2396
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:336
Commodity handling public routines.
void gnc_pricedb_commit_edit(GNCPriceDB *)
Commit an edit.
Definition: gnc-pricedb.c:452
PriceList * gnc_pricedb_get_prices(GNCPriceDB *db, const gnc_commodity *commodity, const gnc_commodity *currency)
Return all the prices for a given commodity in another.
Definition: gnc-pricedb.c:2104