GnuCash  4.12-558-g06612b8434
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_STOCK_TRANSACTION,// "user:stock-transaction"
179  PRICE_SOURCE_INVOICE, // "user:invoice-post"
180  PRICE_SOURCE_TEMP, // "temporary"
181  PRICE_SOURCE_INVALID, // "invalid"
182 } PriceSource;
183 
184 #define PRICE_TYPE_LAST "last"
185 #define PRICE_TYPE_UNK "unknown"
186 #define PRICE_TYPE_TRN "transaction"
187 /* ------------------ */
193 /*@ dependent @*/
194 GNCPrice *gnc_price_create(QofBook *book);
195 
199 GNCPrice *gnc_price_clone(GNCPrice* p, QofBook *book);
200 
209 GNCPrice *gnc_price_invert(GNCPrice *p);
210 
213 /* ------------------ */
219 void gnc_price_ref(GNCPrice *p);
220 
223 void gnc_price_unref(GNCPrice *p);
226 /* ------------------ */
238 void gnc_price_begin_edit (GNCPrice *p);
239 void gnc_price_commit_edit (GNCPrice *p);
240 
241 void gnc_price_set_commodity(GNCPrice *p, gnc_commodity *c);
242 void gnc_price_set_currency(GNCPrice *p, gnc_commodity *c);
243 void gnc_price_set_time64(GNCPrice *p, time64 t);
244 void gnc_price_set_source(GNCPrice *p, PriceSource source);
245 void gnc_price_set_source_string(GNCPrice *p, const char* s);
246 void gnc_price_set_typestr(GNCPrice *p, const char* type);
247 void gnc_price_set_value(GNCPrice *p, gnc_numeric value);
250 /* ------------------ */
256  GNCPrice * gnc_price_lookup (const GncGUID *guid, QofBook *book);
257 /*@ dependent @*/
258 gnc_commodity * gnc_price_get_commodity(const GNCPrice *p);
259 /*@ dependent @*/
260 gnc_commodity * gnc_price_get_currency(const GNCPrice *p);
261 time64 gnc_price_get_time64(const GNCPrice *p);
262 PriceSource gnc_price_get_source(const GNCPrice *p);
263 const char * gnc_price_get_source_string(const GNCPrice *p);
264 const char * gnc_price_get_typestr(const GNCPrice *p);
265 gnc_numeric gnc_price_get_value(const GNCPrice *p);
266 gboolean gnc_price_equal(const GNCPrice *p1, const GNCPrice *p2);
267 
268 #define gnc_price_get_guid(X) qof_entity_get_guid(QOF_INSTANCE(X))
269 #define gnc_price_return_guid(X) (*(qof_entity_get_guid(QOF_INSTANCE(X))))
270 #define gnc_price_get_book(X) qof_instance_get_book(QOF_INSTANCE(X))
271 
276 void gnc_price_print(GNCPrice *db, FILE *f, int indent);
285 #define CURRENCY_DENOM 10000
286 #define COMMODITY_DENOM_MULT 10000
287 
288 /* ================================================================ */
303 gboolean gnc_price_list_insert(PriceList **prices, GNCPrice *p,
304  gboolean check_dupl);
305 
308 gboolean gnc_price_list_remove(PriceList **prices, GNCPrice *p);
309 
312 void gnc_price_list_destroy(PriceList *prices);
313 
314 gboolean gnc_price_list_equal(PriceList *prices1, PriceList *prices2);
318 /* ================================================================ */
331 typedef struct gnc_price_db_s GNCPriceDB;
332 
337 GNCPriceDB * gnc_pricedb_get_db(QofBook *book);
342 GNCPriceDB * gnc_collection_get_pricedb(QofCollection *col);
343 
350 void gnc_pricedb_destroy(GNCPriceDB *db);
351 
353 void gnc_pricedb_begin_edit (GNCPriceDB *);
355 void gnc_pricedb_commit_edit (GNCPriceDB *);
356 
363 void gnc_pricedb_set_bulk_update(GNCPriceDB *db, gboolean bulk_update);
364 
373 gboolean gnc_pricedb_add_price(GNCPriceDB *db, GNCPrice *p);
374 
379 gboolean gnc_pricedb_remove_price(GNCPriceDB *db, GNCPrice *p);
380 
381 typedef enum
382 {
383  PRICE_REMOVE_SOURCE_FQ = 1, // this flag is set when added by F:Q checked
384  PRICE_REMOVE_SOURCE_USER = 2, // this flag is set when added by the user checked
385  PRICE_REMOVE_SOURCE_APP = 4, // this flag is set when added by the app checked
386  PRICE_REMOVE_SOURCE_COMM = 8, // this flag is set when we have commodities selected
387 } PriceRemoveSourceFlags;
388 
389 typedef enum
390 {
391  PRICE_REMOVE_KEEP_NONE, // keep none
392  PRICE_REMOVE_KEEP_LAST_WEEKLY, // leave last one of every week
393  PRICE_REMOVE_KEEP_LAST_MONTHLY, // leave last one of every month
394  PRICE_REMOVE_KEEP_LAST_QUARTERLY, // leave last one of every quarter
395  PRICE_REMOVE_KEEP_LAST_PERIOD, // leave last one of every annual period
396  PRICE_REMOVE_KEEP_SCALED, // leave one every week then one a month
397 } PriceRemoveKeepOptions;
398 
408 gboolean gnc_pricedb_remove_old_prices(GNCPriceDB *db, GList *comm_list,
409  GDate *fiscal_end_date, time64 cutoff,
410  PriceRemoveSourceFlags source,
411  PriceRemoveKeepOptions keep);
412 
422 GNCPrice * gnc_pricedb_lookup_latest(GNCPriceDB *db,
423  const gnc_commodity *commodity,
424  const gnc_commodity *currency);
425 
435 PriceList * gnc_pricedb_lookup_latest_any_currency(GNCPriceDB *db,
436  const gnc_commodity *commodity);
437 
448 gboolean gnc_pricedb_has_prices(GNCPriceDB *db,
449  const gnc_commodity *commodity,
450  const gnc_commodity *currency);
451 
462 PriceList * gnc_pricedb_get_prices(GNCPriceDB *db,
463  const gnc_commodity *commodity,
464  const gnc_commodity *currency);
465 
476 /* NOT USED */
477 GNCPrice * gnc_pricedb_lookup_at_time64(GNCPriceDB *db,
478  const gnc_commodity *commodity,
479  const gnc_commodity *currency,
480  time64 t);
481 
494 GNCPrice * gnc_pricedb_lookup_day_t64(GNCPriceDB *db,
495  const gnc_commodity *commodity,
496  const gnc_commodity *currency,
497  time64 t);
498 
510 GNCPrice * gnc_pricedb_lookup_nearest_in_time64(GNCPriceDB *db,
511  const gnc_commodity *c,
512  const gnc_commodity *currency,
513  time64 t);
514 
527 PriceList * gnc_pricedb_lookup_nearest_in_time_any_currency_t64(GNCPriceDB *db,
528  const gnc_commodity *c,
529  time64 t);
530 
542 GNCPrice * gnc_pricedb_lookup_nearest_before_t64 (GNCPriceDB *db,
543  const gnc_commodity *c,
544  const gnc_commodity *currency,
545  time64 t);
546 
557 PriceList * gnc_pricedb_lookup_nearest_before_any_currency_t64 (GNCPriceDB *db,
558  const gnc_commodity *c,
559  time64 t);
560 
570 gnc_numeric gnc_pricedb_get_nearest_before_price (GNCPriceDB *pdb,
571  const gnc_commodity *orig_currency,
572  const gnc_commodity *new_currency,
573  const time64 t);
574 
584 gnc_numeric gnc_pricedb_get_nearest_price (GNCPriceDB *pdb,
585  const gnc_commodity *orig_currency,
586  const gnc_commodity *new_currency,
587  const time64 t);
588 
596 gnc_numeric gnc_pricedb_get_latest_price (GNCPriceDB *pdb,
597  const gnc_commodity *orig_currency,
598  const gnc_commodity *new_currency);
599 
600 
610 gnc_numeric
612  gnc_numeric balance,
613  const gnc_commodity *balance_currency,
614  const gnc_commodity *new_currency);
615 
626 gnc_numeric
628  gnc_numeric balance,
629  const gnc_commodity *balance_currency,
630  const gnc_commodity *new_currency,
631  time64 t);
632 
643 gnc_numeric
645  gnc_numeric balance,
646  const gnc_commodity *balance_currency,
647  const gnc_commodity *new_currency,
648  time64 t);
649 
650 typedef gboolean (*GncPriceForeachFunc)(GNCPrice *p, gpointer user_data);
651 
666 gboolean gnc_pricedb_foreach_price(GNCPriceDB *db,
667  GncPriceForeachFunc f,
668  gpointer user_data,
669  gboolean stable_order);
670 
676 int
677 gnc_pricedb_num_prices(GNCPriceDB *db,
678  const gnc_commodity *c);
679 
687 GNCPrice *
688 gnc_pricedb_nth_price (GNCPriceDB *db,
689  const gnc_commodity *c,
690  const int n);
691 
692 void gnc_pricedb_nth_price_reset_cache (GNCPriceDB *db);
693 
694 /* The following two convenience functions are used to test the xml backend */
699 guint gnc_pricedb_get_num_prices(GNCPriceDB *db);
700 
704 gboolean gnc_pricedb_equal (GNCPriceDB *db1, GNCPriceDB *db2);
705 
709 void gnc_pricedb_print_contents(GNCPriceDB *db, FILE *f);
716 #define PRICE_COMMODITY "price-commodity"
717 #define PRICE_CURRENCY "price-currency"
718 #define PRICE_DATE "price-date"
719 #define PRICE_SOURCE "price-source"
720 #define PRICE_TYPE "price-type"
721 #define PRICE_VALUE "price-value"
722 
726 #ifdef __cplusplus
727 } /* extern "C" */
728 #endif
729 
730 #endif /* GNC_PRICEDB_H */
731 
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:2237
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:2185
void gnc_pricedb_print_contents(GNCPriceDB *db, FILE *f)
This simple function can be useful for debugging the pricedb code.
Definition: gnc-pricedb.c:3010
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:2246
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:2139
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:1169
GNCPriceDB * gnc_collection_get_pricedb(QofCollection *col)
Return the pricedb via the Book&#39;s collection.
Definition: gnc-pricedb.c:959
gboolean gnc_pricedb_equal(GNCPriceDB *db1, GNCPriceDB *db2)
Test equality of two pricedbs.
Definition: gnc-pricedb.c:1043
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:2614
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:1605
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:2623
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:2679
GNCPriceDB * gnc_pricedb_get_db(QofBook *book)
Return the pricedb associated with the book.
Definition: gnc-pricedb.c:966
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:2658
void gnc_pricedb_destroy(GNCPriceDB *db)
Destroy the given pricedb and unref all of the prices it contains.
Definition: gnc-pricedb.c:922
guint gnc_pricedb_get_num_prices(GNCPriceDB *db)
Return the number of prices in the database.
Definition: gnc-pricedb.c:988
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:2954
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:2605
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:2024
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:2016
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:1276
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:2390
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:2069
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:2668
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:938
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:2874
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:1791
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:2044
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:2400
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:2108