|
GnuCash 2.3.0
|
|
GnuCash 2.3.0
|
Data Structures | |
| struct | GncLotClass |
Files | |
| file | gnc-lot.h |
Defines | |
| #define | GNCLotClass GncLotClass |
| #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)) |
| #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" |
Functions | |
| GType | gnc_lot_get_type (void) |
| GNCLot * | gnc_lot_new (QofBook *) |
| void | gnc_lot_destroy (GNCLot *) |
| 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) |
| void | gnc_lot_add_split (GNCLot *, Split *) |
| void | gnc_lot_remove_split (GNCLot *, Split *) |
| SplitList * | gnc_lot_get_split_list (const GNCLot *) |
| gint | gnc_lot_count_splits (const GNCLot *) |
| Account * | gnc_lot_get_account (const GNCLot *) |
| void | gnc_lot_set_account (GNCLot *, Account *) |
| gnc_numeric | gnc_lot_get_balance (GNCLot *) |
| void | gnc_lot_get_balance_before (const GNCLot *, const Split *, gnc_numeric *, gnc_numeric *) |
| gboolean | gnc_lot_is_closed (GNCLot *) |
| Split * | gnc_lot_get_earliest_split (GNCLot *lot) |
| Split * | gnc_lot_get_latest_split (GNCLot *lot) |
| void | gnc_lot_set_closed_unknown (GNCLot *) |
| 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 *) |
| KvpFrame * | gnc_lot_get_slots (const GNCLot *) |
| GNCLot * | gnc_lot_make_default (Account *acc) |
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.
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.
Definition at line 490 of file gnc-lot.c.
{
LotPrivate* priv;
Account * acc;
if (!lot || !split) return;
priv = GET_PRIVATE(lot);
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));
gnc_lot_begin_edit(lot);
acc = xaccSplitGetAccount (split);
qof_instance_set_dirty(QOF_INSTANCE(lot));
if (NULL == priv->account)
{
xaccAccountInsertLot (acc, lot);
}
else if (priv->account != acc)
{
PERR ("splits from different accounts cannot "
"be added to this lot!\n"
"\tlot account=\'%s\', split account=\'%s\'\n",
xaccAccountGetName(priv->account), xaccAccountGetName (acc));
gnc_lot_commit_edit(lot);
LEAVE("different accounts");
return;
}
if (lot == split->lot)
{
gnc_lot_commit_edit(lot);
LEAVE("already in lot");
return; /* handle not-uncommon no-op */
}
if (split->lot)
{
gnc_lot_remove_split (split->lot, split);
}
xaccSplitSetLot(split, lot);
priv->splits = g_list_append (priv->splits, split);
/* for recomputation of is-closed */
priv->is_closed = LOT_CLOSED_UNKNOWN;
gnc_lot_commit_edit(lot);
qof_event_gen (QOF_INSTANCE(lot), QOF_EVENT_MODIFY, NULL);
LEAVE("added to lot");
}
The gnc_lot_get_account() routine returns the account with which this lot is associated.
Definition at line 306 of file gnc-lot.c.
{
LotPrivate* priv;
if (!lot) return NULL;
priv = GET_PRIVATE(lot);
return priv->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 399 of file gnc-lot.c.
{
LotPrivate* priv;
GList *node;
gnc_numeric zero = gnc_numeric_zero();
gnc_numeric baln = zero;
if (!lot) return zero;
priv = GET_PRIVATE(lot);
if (!priv->splits)
{
priv->is_closed = FALSE;
return zero;
}
/* Sum over splits; because they all belong to same account
* they will have same denominator.
*/
for (node = priv->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))
{
priv->is_closed = TRUE;
}
else
{
priv->is_closed = FALSE;
}
return baln;
}
| void gnc_lot_get_balance_before | ( | const GNCLot * | , |
| const Split * | , | ||
| gnc_numeric * | , | ||
| gnc_numeric * | |||
| ) |
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.
Definition at line 440 of file gnc-lot.c.
{
LotPrivate* priv;
GList *node;
gnc_numeric zero = gnc_numeric_zero();
gnc_numeric amt = zero;
gnc_numeric val = zero;
*amount = amt;
*value = val;
if (lot == NULL) return;
priv = GET_PRIVATE(lot);
if (priv->splits)
{
Transaction *ta, *tb;
const Split *target;
/* If this is a gains split, find the source of the gains and use
its transaction for the comparison. Gains splits are in separate
transactions that may sort after non-gains transactions. */
target = xaccSplitGetGainsSourceSplit (split);
if (target == NULL)
target = split;
tb = xaccSplitGetParent (target);
for (node = priv->splits; node; node = node->next)
{
Split *s = node->data;
Split *source = xaccSplitGetGainsSourceSplit (s);
if (source == NULL)
source = s;
ta = xaccSplitGetParent (source);
if ((ta == tb && source != target) ||
xaccTransOrder (ta, tb) < 0)
{
gnc_numeric tmpval = xaccSplitGetAmount (s);
amt = gnc_numeric_add_fixed (amt, tmpval);
tmpval = xaccSplitGetValue (s);
val = gnc_numeric_add_fixed (val, tmpval);
}
}
}
*amount = amt;
*value = val;
}
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 568 of file gnc-lot.c.
{
LotPrivate* priv;
if (!lot) return NULL;
priv = GET_PRIVATE(lot);
if (! priv->splits) return NULL;
priv->splits = g_list_sort (priv->splits, (GCompareFunc) xaccSplitOrderDateOnly);
return priv->splits->data;
}
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 580 of file gnc-lot.c.
{
LotPrivate* priv;
SplitList *node;
if (!lot) return NULL;
priv = GET_PRIVATE(lot);
if (! priv->splits) return NULL;
priv->splits = g_list_sort (priv->splits, (GCompareFunc) xaccSplitOrderDateOnly);
for (node = priv->splits; node->next; node = node->next)
;
return node->data;
}
Every lot has a place to hang kvp data. This routine returns that place.
Definition at line 337 of file gnc-lot.c.
{
return qof_instance_get_slots(QOF_INSTANCE(lot));
}
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.
Definition at line 343 of file gnc-lot.c.
{
LotPrivate* priv;
if (!lot) return NULL;
priv = GET_PRIVATE(lot);
return priv->splits;
}
| const char* gnc_lot_get_title | ( | const GNCLot * | ) |
Get and set the account title, or the account notes, or the marker.
Definition at line 363 of file gnc-lot.c.
{
if (!lot) return NULL;
return kvp_frame_get_string (gnc_lot_get_slots(lot), "/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 296 of file gnc-lot.c.
{
LotPrivate* priv;
if (!lot) return TRUE;
priv = GET_PRIVATE(lot);
if (0 > priv->is_closed) gnc_lot_get_balance (lot);
return priv->is_closed;
}
XXX: Document?
Definition at line 675 of file gnc-lot.c.
{
GNCLot * lot;
gint64 id;
char buff[200];
lot = gnc_lot_new (qof_instance_get_book(acc));
/* Provide a reasonable title for the new lot */
xaccAccountBeginEdit (acc);
id = kvp_frame_get_gint64 (xaccAccountGetSlots (acc), "/lot-mgmt/next-id");
snprintf (buff, 200, ("%s %" G_GINT64_FORMAT), _("Lot"), id);
kvp_frame_set_str (gnc_lot_get_slots (lot), "/title", buff);
id ++;
kvp_frame_set_gint64 (xaccAccountGetSlots (acc), "/lot-mgmt/next-id", id);
qof_instance_set_dirty (QOF_INSTANCE(acc));
xaccAccountCommitEdit (acc);
return lot;
}
| void gnc_lot_set_closed_unknown | ( | GNCLot * | ) |
Reset closed flag so that it will be recalculated.
Definition at line 326 of file gnc-lot.c.
{
LotPrivate* priv;
if (lot != NULL)
{
priv = GET_PRIVATE(lot);
priv->is_closed = LOT_CLOSED_UNKNOWN;
}
}
1.7.4