Lots: Core Function for AR/AP, Inventory, Stock Lots, Cap Gains
[GnuCash Engine: Core, Non-GUI Accounting Functions]

---

Detailed Description

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 accunt 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.

Files
file	gnc-lot.h
Defines
#define	gnc_lot_get_guid(X)   qof_entity_get_guid(QOF_ENTITY(X))
#define	LOT_IS_CLOSED   "is-closed?"
#define	LOT_BALANCE   "balance"
#define	LOT_TITLE   "lot-title"
#define	LOT_NOTES   "notes"
Functions
GNCLot *	gnc_lot_new (QofBook *)
void	gnc_lot_destroy (GNCLot *)
GNCLot *	gnc_lot_lookup (const GUID *guid, QofBook *book)
QofBook *	gnc_lot_get_book (GNCLot *)
void	gnc_lot_add_split (GNCLot *, Split *)
void	gnc_lot_remove_split (GNCLot *, Split *)
SplitList *	gnc_lot_get_split_list (GNCLot *)
gint	gnc_lot_count_splits (GNCLot *)
Account *	gnc_lot_get_account (GNCLot *)
gnc_numeric	gnc_lot_get_balance (GNCLot *)
gboolean	gnc_lot_is_closed (GNCLot *)
Split *	gnc_lot_get_earliest_split (GNCLot *lot)
Split *	gnc_lot_get_latest_split (GNCLot *lot)
const char *	gnc_lot_get_title (GNCLot *)
const char *	gnc_lot_get_notes (GNCLot *)
void	gnc_lot_set_title (GNCLot *, const char *)
void	gnc_lot_set_notes (GNCLot *, const char *)
KvpFrame *	gnc_lot_get_slots (GNCLot *)

---

Function Documentation

void gnc_lot_add_split (  GNCLot *  , Split *  )

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 polciy, use the xaccSplitAssignToLot() routine instead. Definition at line 243 of file gnc-lot.c. { Account * acc; if (!lot || !split) return; ENTER ("(lot=%p, split=%p) %s amt=%s val=%s", lot, split, gnc_lot_get_title (lot), gnc_num_dbg_to_string (split->amount), gnc_num_dbg_to_string (split->value)); acc = xaccSplitGetAccount (split); if (NULL == lot->account) { xaccAccountInsertLot (acc, lot); } else if (lot->account != acc) { PERR ("splits from different accounts cannot " "be added to this lot!\n" "\tlot account=\'%s\', split account=\'%s\'\n", xaccAccountGetName(lot->account), xaccAccountGetName (acc)); return; } if (lot == split->lot) return; /* handle not-uncommon no-op */ if (split->lot) { gnc_lot_remove_split (split->lot, split); } split->lot = lot; lot->splits = g_list_append (lot->splits, split); /* for recomputation of is-closed */ lot->is_closed = -1; gnc_engine_gen_event (&lot->entity, GNC_EVENT_MODIFY); }

Account* gnc_lot_get_account (  GNCLot *   )

The gnc_lot_get_account() routine returns the account with which this lot is associated. Definition at line 144 of file gnc-lot.c. { if (!lot) return NULL; return lot->account; }

gnc_numeric gnc_lot_get_balance (  GNCLot *   )

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. Definition at line 204 of file gnc-lot.c. { GList *node; gnc_numeric zero = gnc_numeric_zero(); gnc_numeric baln = zero; if (!lot) return zero; if (!lot->splits) { lot->is_closed = FALSE; return zero; } /* Sum over splits; because they all belong to same account * they will have same denominator. */ for (node=lot->splits; node; node=node->next) { Split *s = node->data; gnc_numeric amt = xaccSplitGetAmount (s); baln = gnc_numeric_add_fixed (baln, amt); } /* cache a zero balance as a closed lot */ if (gnc_numeric_equal (baln, zero)) { lot->is_closed = TRUE; } else { lot->is_closed = FALSE; } return baln; }

Split* gnc_lot_get_earliest_split (  GNCLot *  lot  )

The gnc_lot_get_earliest_split() routine is a convenience routine that helps identify the date this lot was opened. It simply loops over all of the splits in the lot, and returns the split with the earliest split->transaction->date_posted. Definition at line 303 of file gnc-lot.c. { SplitList *node; Timespec ts; Split *earliest = NULL; ts.tv_sec = ((long long) LONG_MAX); ts.tv_nsec = 0; if (!lot) return NULL; for (node=lot->splits; node; node=node->next) { Split *s = node->data; Transaction *trans = s->parent; if (!trans) continue; if ((ts.tv_sec > trans->date_posted.tv_sec) || ((ts.tv_sec == trans->date_posted.tv_sec) && (ts.tv_nsec > trans->date_posted.tv_nsec))) { ts = trans->date_posted; earliest = s; } } return earliest; }

Split* gnc_lot_get_latest_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. Definition at line 332 of file gnc-lot.c. { SplitList *node; Timespec ts; Split *latest = NULL; ts.tv_sec = -((long long) LONG_MAX); ts.tv_nsec = 0; if (!lot) return NULL; for (node=lot->splits; node; node=node->next) { Split *s = node->data; Transaction *trans = s->parent; if (!trans) continue; if ((ts.tv_sec < trans->date_posted.tv_sec) || ((ts.tv_sec == trans->date_posted.tv_sec) && (ts.tv_nsec < trans->date_posted.tv_nsec))) { ts = trans->date_posted; latest = s; } } return latest; }

KvpFrame* gnc_lot_get_slots (  GNCLot *   )

Every lot has a place to hang kvp data. This routine returns that place. Definition at line 151 of file gnc-lot.c. { if (!lot) return NULL; return lot->kvp_data; }

SplitList* gnc_lot_get_split_list (  GNCLot *   )

The gnc_lot_get_split_list() routine returns a GList of all the splits in this lot. Do *not* not free this list when done; it is a pointer straight into the lots intenal 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. Definition at line 158 of file gnc-lot.c. { if (!lot) return NULL; return lot->splits; }

const char* gnc_lot_get_title (  GNCLot *   )

Get and set the account title, or the account notes. Definition at line 174 of file gnc-lot.c. { if (!lot) return NULL; return kvp_frame_get_string (lot->kvp_data, "/title"); }

gboolean gnc_lot_is_closed (  GNCLot *   )

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. Definition at line 136 of file gnc-lot.c. { if (!lot) return TRUE; if (0 > lot->is_closed) gnc_lot_get_balance (lot); return lot->is_closed; }

---