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

Files
file	gnc-lot.h

Data Structures
struct	GncLotClass

Macros
#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 *)
	Adds a split to this lot.
void	gnc_lot_remove_split (GNCLot *, Split *)
	Adds a split from this lot.
SplitList *	gnc_lot_get_split_list (const GNCLot *)
	Returns a list of all the splits in this lot.
gint	gnc_lot_count_splits (const GNCLot *)
Account *	gnc_lot_get_account (const GNCLot *)
	Returns the account with which this lot is associated.
void	gnc_lot_set_account (GNCLot *, Account *)
GncInvoice *	gnc_lot_get_cached_invoice (const GNCLot *lot)
	Returns the invoice with which this lot is associated.
void	gnc_lot_set_cached_invoice (GNCLot *lot, GncInvoice *invoice)
gnc_numeric	gnc_lot_get_balance (GNCLot *)
	Returns the lot balance.
void	gnc_lot_get_balance_before (const GNCLot *, const Split *, gnc_numeric *, gnc_numeric *)
	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.
gboolean	gnc_lot_is_closed (GNCLot *)
	Returns closed status of the given lot.
Split *	gnc_lot_get_earliest_split (GNCLot *lot)
	Convenience routine to identify the earliest date in the lot.
Split *	gnc_lot_get_latest_split (GNCLot *lot)
	Convenience routineto identify the date this lot was closed.
void	gnc_lot_set_closed_unknown (GNCLot *)
	Reset closed flag so that it will be recalculated.
GNCLot *	gnc_lot_make_default (Account *acc)

Get/set the account title and notes.
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 *)

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

Macro Definition Documentation

GNC_IS_LOT

#define GNC_IS_LOT

(

o

)

(G_TYPE_CHECK_INSTANCE_TYPE ((o), GNC_TYPE_LOT))

Definition at line 85 of file gnc-lot.h.

GNC_IS_LOT_CLASS

#define GNC_IS_LOT_CLASS

(

k

)

(G_TYPE_CHECK_CLASS_TYPE ((k), GNC_TYPE_LOT))

Definition at line 87 of file gnc-lot.h.

GNC_LOT

#define GNC_LOT

(

o

)

(G_TYPE_CHECK_INSTANCE_CAST ((o), GNC_TYPE_LOT, GNCLot))

Definition at line 81 of file gnc-lot.h.

GNC_LOT_CLASS

#define GNC_LOT_CLASS

(

k

)

(G_TYPE_CHECK_CLASS_CAST((k), GNC_TYPE_LOT, GNCLotClass))

Definition at line 83 of file gnc-lot.h.

GNC_LOT_GET_CLASS

#define GNC_LOT_GET_CLASS

(

o

)

(G_TYPE_INSTANCE_GET_CLASS ((o), GNC_TYPE_LOT, GNCLotClass))

Definition at line 89 of file gnc-lot.h.

gnc_lot_get_guid

#define gnc_lot_get_guid

(

X

)

qof_entity_get_guid(QOF_INSTANCE(X))

Definition at line 193 of file gnc-lot.h.

GNC_TYPE_LOT

#define GNC_TYPE_LOT   (gnc_lot_get_type ())

Definition at line 80 of file gnc-lot.h.

GNCLotClass

#define GNCLotClass   GncLotClass

Definition at line 77 of file gnc-lot.h.

LOT_BALANCE

#define LOT_BALANCE   "balance"

Definition at line 196 of file gnc-lot.h.

LOT_IS_CLOSED

#define LOT_IS_CLOSED   "is-closed?"

Definition at line 195 of file gnc-lot.h.

LOT_NOTES

#define LOT_NOTES   "notes"

Definition at line 198 of file gnc-lot.h.

LOT_TITLE

#define LOT_TITLE   "lot-title"

Definition at line 197 of file gnc-lot.h.

Function Documentation

gnc_lot_add_split()

void gnc_lot_add_split	(	GNCLot *	lot,
		Split *	split
	)

Adds a split to this lot.

Note

• All splits in a lot must be in the same account.
• Splits are added unconditionally, with no regard for the accounting policy. To enforce a particular accounting policy, use the xaccSplitAssignToLot() routine instead.

Definition at line 579 of file gnc-lot.cpp.

{
    GNCLotPrivate* 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 (nullptr == 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, nullptr);
    LEAVE("added to lot");
}

gnc_lot_begin_edit()

void gnc_lot_begin_edit

(

GNCLot *

lot

)

Definition at line 320 of file gnc-lot.cpp.

{
    qof_begin_edit(QOF_INSTANCE(lot));
}

gnc_lot_commit_edit()

void gnc_lot_commit_edit

(

GNCLot *

lot

)

Definition at line 341 of file gnc-lot.cpp.

{
    if (!qof_commit_edit (QOF_INSTANCE(lot))) return;
    qof_commit_edit_part2 (QOF_INSTANCE(lot), commit_err, noop, lot_free);
}

gnc_lot_count_splits()

gint gnc_lot_count_splits

(

const GNCLot *

lot

)

Definition at line 433 of file gnc-lot.cpp.

{
    GNCLotPrivate* priv;
    if (!lot) return 0;
    priv = GET_PRIVATE(lot);
    return g_list_length (priv->splits);
}

gnc_lot_destroy()

void gnc_lot_destroy

(

GNCLot *

lot

)

Definition at line 308 of file gnc-lot.cpp.

{
    if (!lot) return;
 
    gnc_lot_begin_edit(lot);
    qof_instance_set_destroying(lot, TRUE);
    gnc_lot_commit_edit(lot);
}

gnc_lot_get_account()

Account * gnc_lot_get_account

(

const GNCLot *

lot

)

Returns the account with which this lot is associated.

Definition at line 377 of file gnc-lot.cpp.

{
    GNCLotPrivate* priv;
    if (!lot) return nullptr;
    priv = GET_PRIVATE(lot);
    return priv->account;
}

gnc_lot_get_balance()

gnc_numeric gnc_lot_get_balance

(

GNCLot *

lot

)

Returns the lot balance.

This balance will be expressed in the lot account's commodity.

Definition at line 487 of file gnc-lot.cpp.

{
    GNCLotPrivate* 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 = GNC_SPLIT(node->data);
        gnc_numeric amt = xaccSplitGetAdjustedAmount (s);
        baln = gnc_numeric_add_fixed (baln, amt);
        g_assert (gnc_numeric_check (baln) == GNC_ERROR_OK);
    }
 
    /* 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;
}

gnc_lot_get_balance_before()

void gnc_lot_get_balance_before	(	const GNCLot *	lot,
		const Split *	split,
		gnc_numeric *	amount,
		gnc_numeric *	value
	)

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 529 of file gnc-lot.cpp.

{
    GNCLotPrivate* priv;
    GList *node;
    gnc_numeric zero = gnc_numeric_zero();
    gnc_numeric amt = zero;
    gnc_numeric val = zero;
 
    *amount = amt;
    *value = val;
    if (lot == nullptr) 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 == nullptr)
            target = split;
        tb = xaccSplitGetParent (target);
        for (node = priv->splits; node; node = node->next)
        {
            Split *s = GNC_SPLIT(node->data);
            Split *source = xaccSplitGetGainsSourceSplit (s);
            if (source == nullptr)
                source = s;
            ta = xaccSplitGetParent (source);
            if ((ta == tb && source != target) ||
                    xaccTransOrder (ta, tb) < 0)
            {
                gnc_numeric tmpval = xaccSplitGetAdjustedAmount (s);
                amt = gnc_numeric_add_fixed (amt, tmpval);
                tmpval = xaccSplitGetValue (s);
                val = gnc_numeric_add_fixed (val, tmpval);
            }
        }
    }
 
    *amount = amt;
    *value = val;
}

gnc_lot_get_book()

QofBook * gnc_lot_get_book

(

GNCLot *

lot

)

Definition at line 359 of file gnc-lot.cpp.

{
    return qof_instance_get_book(QOF_INSTANCE(lot));
}

gnc_lot_get_cached_invoice()

GncInvoice * gnc_lot_get_cached_invoice

(

const GNCLot *

lot

)

Returns the invoice with which this lot is associated.

Definition at line 385 of file gnc-lot.cpp.

{
     if (!lot) return nullptr;
     else
     {
         GNCLotPrivate *priv = GET_PRIVATE(lot);
         return priv->cached_invoice;
     }
}

gnc_lot_get_earliest_split()

Split * gnc_lot_get_earliest_split

(

GNCLot *

lot

)

Convenience routine to identify the earliest date in the lot.

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

Definition at line 658 of file gnc-lot.cpp.

{
    GNCLotPrivate* priv;
    if (!lot) return nullptr;
    priv = GET_PRIVATE(lot);
    if (! priv->splits) return nullptr;
    priv->splits = g_list_sort (priv->splits, (GCompareFunc) xaccSplitOrderDateOnly);
    return GNC_SPLIT(priv->splits->data);
}

gnc_lot_get_latest_split()

Split * gnc_lot_get_latest_split

(

GNCLot *

lot

)

Convenience routineto 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 670 of file gnc-lot.cpp.

{
    GNCLotPrivate* priv;
    SplitList *node;
 
    if (!lot) return nullptr;
    priv = GET_PRIVATE(lot);
    if (! priv->splits) return nullptr;
    priv->splits = g_list_sort (priv->splits, (GCompareFunc) xaccSplitOrderDateOnly);
 
    for (node = priv->splits; node->next; node = node->next)
        ;
 
    return GNC_SPLIT(node->data);
}

gnc_lot_get_notes()

const char * gnc_lot_get_notes

(

const GNCLot *

lot

)

Definition at line 454 of file gnc-lot.cpp.

{
    if (!lot) return nullptr;
 
    auto str{qof_instance_get_path_kvp<const char*> (QOF_INSTANCE (lot), {"notes"})};
    return str ? *str : nullptr;
}

gnc_lot_get_split_list()

SplitList * gnc_lot_get_split_list

(

const GNCLot *

lot

)

Returns a list of all the splits in this lot.

Returns

GList

This GList is owned and managed by the lot.

• Do not free it when done.
• Do not modify it directly
• Calls to either gnc_lot_add_split() or gnc_lot_remove_split() will invalidate the returned pointer

Definition at line 425 of file gnc-lot.cpp.

{
    GNCLotPrivate* priv;
    if (!lot) return nullptr;
    priv = GET_PRIVATE(lot);
    return priv->splits;
}

gnc_lot_get_title()

const char * gnc_lot_get_title

(

const GNCLot *

lot

)

Definition at line 445 of file gnc-lot.cpp.

{
    if (!lot) return nullptr;
 
    auto str{qof_instance_get_path_kvp<const char*> (QOF_INSTANCE (lot), {"title"})};
    return str ? *str : nullptr;
}

gnc_lot_is_closed()

gboolean gnc_lot_is_closed

(

GNCLot *

lot

)

Returns closed status of the given lot.

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.

Returns

boolean

Definition at line 367 of file gnc-lot.cpp.

{
    GNCLotPrivate* priv;
    if (!lot) return TRUE;
    priv = GET_PRIVATE(lot);
    if (0 > priv->is_closed) gnc_lot_get_balance (lot);
    return priv->is_closed;
}

gnc_lot_lookup()

GNCLot * gnc_lot_lookup	(	const GncGUID *	guid,
		QofBook *	book
	)

Definition at line 350 of file gnc-lot.cpp.

{
    QofCollection *col;
    if (!guid || !book) return nullptr;
    col = qof_book_get_collection (book, GNC_ID_LOT);
    return (GNCLot *) qof_collection_lookup_entity (col, guid);
}

gnc_lot_make_default()

GNCLot * gnc_lot_make_default

(

Account *

acc

)

Todo:

Document this function ?

Definition at line 765 of file gnc-lot.cpp.

{
    GNCLot * lot;
    gint64 id = 0;
    gchar *buff;
 
    lot = gnc_lot_new (qof_instance_get_book(acc));
 
    /* Provide a reasonable title for the new lot */
    xaccAccountBeginEdit (acc);
    qof_instance_get (QOF_INSTANCE (acc), "lot-next-id", &id, nullptr);
    buff = g_strdup_printf ("%s %" G_GINT64_FORMAT, _("Lot"), id);
    gnc_lot_set_title (lot, buff);
    id ++;
    qof_instance_set (QOF_INSTANCE (acc), "lot-next-id", id, nullptr);
    xaccAccountCommitEdit (acc);
    g_free (buff);
    return lot;
}

gnc_lot_new()

GNCLot * gnc_lot_new

(

QofBook *

book

)

Definition at line 267 of file gnc-lot.cpp.

{
    GNCLot *lot;
    g_return_val_if_fail (book, nullptr);
 
    lot = GNC_LOT(g_object_new (GNC_TYPE_LOT, nullptr));
    qof_instance_init_data(QOF_INSTANCE(lot), GNC_ID_LOT, book);
    qof_event_gen (QOF_INSTANCE(lot), QOF_EVENT_CREATE, nullptr);
    return lot;
}

gnc_lot_remove_split()

void gnc_lot_remove_split	(	GNCLot *	lot,
		Split *	split
	)

Adds a split from this lot.

Definition at line 631 of file gnc-lot.cpp.

{
    GNCLotPrivate* priv;
    if (!lot || !split) return;
    priv = GET_PRIVATE(lot);
 
    ENTER ("(lot=%p, split=%p)", lot, split);
    gnc_lot_begin_edit(lot);
    qof_instance_set_dirty(QOF_INSTANCE(lot));
    priv->splits = g_list_remove (priv->splits, split);
    xaccSplitSetLot(split, nullptr);
    priv->is_closed = LOT_CLOSED_UNKNOWN;   /* force an is-closed computation */
 
    if (!priv->splits && priv->account)
    {
        xaccAccountRemoveLot (priv->account, lot);
        priv->account = nullptr;
    }
    gnc_lot_commit_edit(lot);
    qof_event_gen (QOF_INSTANCE(lot), QOF_EVENT_MODIFY, nullptr);
    LEAVE("removed from lot");
}

gnc_lot_set_account()

void gnc_lot_set_account	(	GNCLot *	lot,
		Account *	account
	)

Definition at line 403 of file gnc-lot.cpp.

{
    if (lot != nullptr)
    {
        GNCLotPrivate* priv;
        priv = GET_PRIVATE(lot);
        priv->account = account;
    }
}

gnc_lot_set_cached_invoice()

void gnc_lot_set_cached_invoice	(	GNCLot *	lot,
		GncInvoice *	invoice
	)

Definition at line 396 of file gnc-lot.cpp.

{
    if (!lot) return;
    GET_PRIVATE(lot)->cached_invoice = invoice;
}

gnc_lot_set_closed_unknown()

void gnc_lot_set_closed_unknown

(

GNCLot *

lot

)

Reset closed flag so that it will be recalculated.

Definition at line 414 of file gnc-lot.cpp.

{
    GNCLotPrivate* priv;
    if (lot != nullptr)
    {
        priv = GET_PRIVATE(lot);
        priv->is_closed = LOT_CLOSED_UNKNOWN;
    }
}

gnc_lot_set_notes()

void gnc_lot_set_notes	(	GNCLot *	lot,
		const char *	str
	)

Definition at line 474 of file gnc-lot.cpp.

{
    if (!lot) return;
 
    qof_begin_edit(QOF_INSTANCE(lot));
    qof_instance_set_path_kvp<const char*> (QOF_INSTANCE (lot), g_strdup(str), {"notes"});
    qof_instance_set_dirty(QOF_INSTANCE(lot));
    gnc_lot_commit_edit(lot);
}

gnc_lot_set_title()

void gnc_lot_set_title	(	GNCLot *	lot,
		const char *	str
	)

Definition at line 463 of file gnc-lot.cpp.

{
    if (!lot) return;
 
    qof_begin_edit(QOF_INSTANCE(lot));
    qof_instance_set_path_kvp<const char*> (QOF_INSTANCE (lot), g_strdup(str), {"title"});
    qof_instance_set_dirty(QOF_INSTANCE(lot));
    gnc_lot_commit_edit(lot);
}