/********************************************************************\ * gnc-lot.h -- AR/AP invoices; inventory lots; stock lots * * * * This program is free software; you can redistribute it and/or * * modify it under the terms of the GNU General Public License as * * published by the Free Software Foundation; either version 2 of * * the License, or (at your option) any later version. * * * * This program is distributed in the hope that it will be useful, * * but WITHOUT ANY WARRANTY; without even the implied warranty of * * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * * GNU General Public License for more details. * * * * You should have received a copy of the GNU General Public License* * along with this program; if not, contact: * * * * Free Software Foundation Voice: +1-617-542-5942 * * 51 Franklin Street, Fifth Floor Fax: +1-617-542-2652 * * Boston, MA 02110-1301, USA gnu@gnu.org * \********************************************************************/ /** @addtogroup Engine @{ */ /** @addtogroup Lot Lots: Core Function for AR/AP, Inventory, Stock Lots, Cap Gains * One often needs to know that the item 'bought' in one transaction * is the same one as the item 'sold' in a different transaction. * Lots are used to make this association. One Lot holds all of the * splits that involve the same item. A lot is typically formed when * the item is bought, and is closed when the item is sold out. * A lot need not be a single item, it can be a quantity of the same * thing e.g. 500 gallons of paint (sold off a few gallons at a time). * * Lots are required to correctly implement invoices, inventory, * depreciation and stock market investment gains. See the file * src/doc/lots.txt for a detailed implementation overview. * * A lot is "closed" when the number of items in the lot has gone to zero. * It is very easy to compute the gains/losses for a closed lot: it is the * sum-total of the values of the items put into/taken out of the lot. * (Realized) Gains on still-open lots can be computed by pro-rating the * purchase prices. * * Lots are nothing more than a collection or grouping of splits in an * account. All of the splits in a lot must belong to the same account; * there's no mix-n-match. Thus, in this sense, a lot belongs to an * account as well. * * Lots have an implicit "opening date": the date of the earliest split in * the lot. The "close date" is the date of the split that brought the lot * item balance down to zero. * @{ */ /** @file gnc-lot.h * * @author Created by Linas Vepstas May 2002 * @author Copyright (c) 2002,2003 Linas Vepstas */ #ifndef GNC_LOT_H #define GNC_LOT_H //typedef struct _GncLotClass GNCLotClass; #include "qof.h" #include "gnc-engine.h" /*#include "gnc-lot-p.h"*/ #include "gncInvoice.h" #ifdef __cplusplus extern "C" { #endif typedef struct { QofInstanceClass parent_class; } GncLotClass; #define GNCLotClass GncLotClass /* --- type macros --- */ #define GNC_TYPE_LOT (gnc_lot_get_type ()) #define GNC_LOT(o) \ (G_TYPE_CHECK_INSTANCE_CAST ((o), GNC_TYPE_LOT, GNCLot)) #define GNC_LOT_CLASS(k) \ (G_TYPE_CHECK_CLASS_CAST((k), GNC_TYPE_LOT, GNCLotClass)) #define GNC_IS_LOT(o) \ (G_TYPE_CHECK_INSTANCE_TYPE ((o), GNC_TYPE_LOT)) #define GNC_IS_LOT_CLASS(k) \ (G_TYPE_CHECK_CLASS_TYPE ((k), GNC_TYPE_LOT)) #define GNC_LOT_GET_CLASS(o) \ (G_TYPE_INSTANCE_GET_CLASS ((o), GNC_TYPE_LOT, GNCLotClass)) GType gnc_lot_get_type(void); /*@ dependent @*/ GNCLot * gnc_lot_new (QofBook *); void gnc_lot_destroy (GNCLot *); /*@ dependent @*/ GNCLot * gnc_lot_lookup (const GncGUID *guid, QofBook *book); QofBook * gnc_lot_get_book (GNCLot *); void gnc_lot_begin_edit (GNCLot *lot); void gnc_lot_commit_edit (GNCLot *lot); /** The gnc_lot_add_split() routine adds a split to this lot. Note * that *all* splits in a lot must also be in the same account. * Note that this routine adds the split unconditionally, with * no regard for the accounting policy. To enforce a particular * accounting policy, use the xaccSplitAssignToLot() routine * instead. */ void gnc_lot_add_split (GNCLot *, Split *); void gnc_lot_remove_split (GNCLot *, Split *); /** The gnc_lot_get_split_list() routine returns a GList of all the * splits in this lot. Do *not* free this list when done; * it is a pointer straight into the lots internal list. Do * *not* add to or remove from this list directly. Calling * either gnc_lot_add_split() or gnc_lot_remove_split() will * invalidate the returned pointer. */ SplitList * gnc_lot_get_split_list (const GNCLot *); gint gnc_lot_count_splits (const GNCLot *); /** The gnc_lot_get_account() routine returns the account with which * this lot is associated. */ /*@ dependent @*/ Account * gnc_lot_get_account (const GNCLot *); void gnc_lot_set_account(GNCLot*, Account*); /** The gnc_lot_get_cached_invoice() routine returns the invoice with * which this lot is associated. */ /*@ dependent @*/ GncInvoice * gnc_lot_get_cached_invoice (const GNCLot *lot); void gnc_lot_set_cached_invoice(GNCLot* lot, GncInvoice *invoice); /** The gnc_lot_get_balance() routine returns the balance of the lot. * The commodity in which this balance is expressed is the commodity * of the account. */ gnc_numeric gnc_lot_get_balance (GNCLot *); /** The gnc_lot_get_balance_before routine computes both the balance and * value in the lot considering only splits in transactions prior to the * one containing the given split or other splits in the same transaction. * The first return value is the amount and the second is the value. */ void gnc_lot_get_balance_before (const GNCLot *, const Split *, gnc_numeric *, gnc_numeric *); /** The gnc_lot_is_closed() routine returns a boolean flag: is this * lot closed? A lot is closed if its balance is zero. This * routine is faster than using gnc_lot_get_balance() because * once the balance goes to zero, this fact is cached. */ gboolean gnc_lot_is_closed (GNCLot *); /** The gnc_lot_get_earliest_split() routine is a convenience routine * that helps identify the earliest date in the lot. It simply * loops over all of the splits in the lot, and returns the split * with the earliest split->transaction->date_posted. It may not * necessarily identify the lot opening split. */ Split * gnc_lot_get_earliest_split (GNCLot *lot); /** The gnc_lot_get_latest_split() routine is a convenience routine * that helps identify the date this lot was closed. It simply * loops over all of the splits in the lot, and returns the split * with the latest split->transaction->date_posted. */ Split * gnc_lot_get_latest_split (GNCLot *lot); /** Reset closed flag so that it will be recalculated. */ void gnc_lot_set_closed_unknown(GNCLot*); /** Get and set the account title, or the account notes, or the marker. */ const char * gnc_lot_get_title (const GNCLot *); const char * gnc_lot_get_notes (const GNCLot *); void gnc_lot_set_title (GNCLot *, const char *); void gnc_lot_set_notes (GNCLot *, const char *); /** XXX: Document? */ GNCLot * gnc_lot_make_default (Account * acc); #define gnc_lot_get_guid(X) qof_entity_get_guid(QOF_INSTANCE(X)) #define LOT_IS_CLOSED "is-closed?" #define LOT_BALANCE "balance" #define LOT_TITLE "lot-title" #define LOT_NOTES "notes" #ifdef __cplusplus } /* extern "C" */ #endif #endif /* GNC_LOT_H */ /** @} */ /** @} */