1 /********************************************************************\ 2 * gnc-lot.h -- AR/AP invoices; inventory lots; stock lots * 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 /** @addtogroup Engine 22 @{ */ 23 /** @addtogroup Lot Lots: Core Function for AR/AP, Inventory, Stock Lots, Cap Gains 24 * One often needs to know that the item 'bought' in one transaction 25 * is the same one as the item 'sold' in a different transaction. 26 * Lots are used to make this association. One Lot holds all of the 27 * splits that involve the same item. A lot is typically formed when 28 * the item is bought, and is closed when the item is sold out. 29 * A lot need not be a single item, it can be a quantity of the same 30 * thing e.g. 500 gallons of paint (sold off a few gallons at a time). 31 * 32 * Lots are required to correctly implement invoices, inventory, 33 * depreciation and stock market investment gains. See the file 34 * src/doc/lots.txt for a detailed implementation overview. 35 * 36 * A lot is "closed" when the number of items in the lot has gone to zero. 37 * It is very easy to compute the gains/losses for a closed lot: it is the 38 * sum-total of the values of the items put into/taken out of the lot. 39 * (Realized) Gains on still-open lots can be computed by pro-rating the 40 * purchase prices. 41 * 42 * Lots are nothing more than a collection or grouping of splits in an 43 * account. All of the splits in a lot must belong to the same account; 44 * there's no mix-n-match. Thus, in this sense, a lot belongs to an 45 * account as well. 46 * 47 * Lots have an implicit "opening date": the date of the earliest split in 48 * the lot. The "close date" is the date of the split that brought the lot 49 * item balance down to zero. 50 * 51 @{ */ 52 53 /** @file gnc-lot.h 54 * 55 * @author Created by Linas Vepstas May 2002 56 * @author Copyright (c) 2002,2003 Linas Vepstas <linas@linas.org> 57 */ 58 59 #ifndef GNC_LOT_H 60 #define GNC_LOT_H 61 62 //typedef struct _GncLotClass GNCLotClass; 63 64 #include "qof.h" 65 #include "gnc-engine.h" 66 /*#include "gnc-lot-p.h"*/ 67 #include "gncInvoice.h" 68 69 #ifdef __cplusplus 70 extern "C" { 71 #endif 72 73 typedef struct 74 { 75 QofInstanceClass parent_class; 76 } GncLotClass; 77 #define GNCLotClass GncLotClass 78 79 /* --- type macros --- */ 80 #define GNC_TYPE_LOT (gnc_lot_get_type ()) 81 #define GNC_LOT(o) \ 82 (G_TYPE_CHECK_INSTANCE_CAST ((o), GNC_TYPE_LOT, GNCLot)) 83 #define GNC_LOT_CLASS(k) \ 84 (G_TYPE_CHECK_CLASS_CAST((k), GNC_TYPE_LOT, GNCLotClass)) 85 #define GNC_IS_LOT(o) \ 86 (G_TYPE_CHECK_INSTANCE_TYPE ((o), GNC_TYPE_LOT)) 87 #define GNC_IS_LOT_CLASS(k) \ 88 (G_TYPE_CHECK_CLASS_TYPE ((k), GNC_TYPE_LOT)) 89 #define GNC_LOT_GET_CLASS(o) \ 90 (G_TYPE_INSTANCE_GET_CLASS ((o), GNC_TYPE_LOT, GNCLotClass)) 91 GType gnc_lot_get_type(void); 92 93 94 /*@ dependent @*/ 95 GNCLot * gnc_lot_new (QofBook *); 96 void gnc_lot_destroy (GNCLot *); 97 98 /*@ dependent @*/ 99 GNCLot * gnc_lot_lookup (const GncGUID *guid, QofBook *book); 100 QofBook * gnc_lot_get_book (GNCLot *); 101 102 void gnc_lot_begin_edit (GNCLot *lot); 103 void gnc_lot_commit_edit (GNCLot *lot); 104 105 /** The gnc_lot_add_split() routine adds a split to this lot. Note 106 * that *all* splits in a lot must also be in the same account. 107 * Note that this routine adds the split unconditionally, with 108 * no regard for the accounting policy. To enforce a particular 109 * accounting policy, use the xaccSplitAssignToLot() routine 110 * instead. 111 */ 112 void gnc_lot_add_split (GNCLot *, Split *); 113 void gnc_lot_remove_split (GNCLot *, Split *); 114 115 /** The gnc_lot_get_split_list() routine returns a GList of all the 116 * splits in this lot. Do *not* free this list when done; 117 * it is a pointer straight into the lots internal list. Do 118 * *not* add to or remove from this list directly. Calling 119 * either gnc_lot_add_split() or gnc_lot_remove_split() will 120 * invalidate the returned pointer. 121 */ 122 SplitList * gnc_lot_get_split_list (const GNCLot *); 123 gint gnc_lot_count_splits (const GNCLot *); 124 125 /** The gnc_lot_get_account() routine returns the account with which 126 * this lot is associated. */ 127 /*@ dependent @*/ 128 Account * gnc_lot_get_account (const GNCLot *); 129 void gnc_lot_set_account(GNCLot*, Account*); 130 131 /** The gnc_lot_get_cached_invoice() routine returns the invoice with 132 * which this lot is associated. */ 133 /*@ dependent @*/ 134 GncInvoice * gnc_lot_get_cached_invoice (const GNCLot *lot); 135 void gnc_lot_set_cached_invoice(GNCLot* lot, GncInvoice *invoice); 136 137 /** The gnc_lot_get_balance() routine returns the balance of the lot. 138 * The commodity in which this balance is expressed is the commodity 139 * of the account. */ 140 gnc_numeric gnc_lot_get_balance (GNCLot *); 141 142 /** The gnc_lot_get_balance_before routine computes both the balance and 143 * value in the lot considering only splits in transactions prior to the 144 * one containing the given split or other splits in the same transaction. 145 * The first return value is the amount and the second is the value. */ 146 void gnc_lot_get_balance_before (const GNCLot *, const Split *, 147 gnc_numeric *, gnc_numeric *); 148 149 /** The gnc_lot_is_closed() routine returns a boolean flag: is this 150 * lot closed? A lot is closed if its balance is zero. This 151 * routine is faster than using gnc_lot_get_balance() because 152 * once the balance goes to zero, this fact is cached. 153 */ 154 gboolean gnc_lot_is_closed (GNCLot *); 155 156 /** The gnc_lot_get_earliest_split() routine is a convenience routine 157 * that helps identify the earliest date in the lot. It simply 158 * loops over all of the splits in the lot, and returns the split 159 * with the earliest split->transaction->date_posted. It may not 160 * necessarily identify the lot opening split. 161 */ 162 Split * gnc_lot_get_earliest_split (GNCLot *lot); 163 164 /** The gnc_lot_get_latest_split() routine is a convenience routine 165 * that helps identify the date this lot was closed. It simply 166 * loops over all of the splits in the lot, and returns the split 167 * with the latest split->transaction->date_posted. 168 */ 169 Split * gnc_lot_get_latest_split (GNCLot *lot); 170 171 /** Reset closed flag so that it will be recalculated. */ 172 void gnc_lot_set_closed_unknown(GNCLot*); 173 174 /** Get and set the account title, or the account notes, or the marker. */ 175 const char * gnc_lot_get_title (const GNCLot *); 176 const char * gnc_lot_get_notes (const GNCLot *); 177 void gnc_lot_set_title (GNCLot *, const char *); 178 void gnc_lot_set_notes (GNCLot *, const char *); 179 180 /** XXX: Document? */ 181 GNCLot * gnc_lot_make_default (Account * acc); 182 183 #define gnc_lot_get_guid(X) qof_entity_get_guid(QOF_INSTANCE(X)) 184 185 #define LOT_IS_CLOSED "is-closed?" 186 #define LOT_BALANCE "balance" 187 #define LOT_TITLE "lot-title" 188 #define LOT_NOTES "notes" 189 190 #ifdef __cplusplus 191 } /* extern "C" */ 192 #endif 193 194 #endif /* GNC_LOT_H */ 195 /** @} */ 196 /** @} */ 197