Transaction, Split

A good overview of transactions, splits and accounts can be found in the texinfo documentation, together with an overview of how to use this API. More...

Files
file	Split.h
	API for Transactions and Splits (journal entries)
file	Transaction.h
	API for Transactions and Splits (journal entries)

Macros
#define	GNC_TYPE_SPLIT   (gnc_split_get_type ())
#define	GNC_SPLIT(o)   (G_TYPE_CHECK_INSTANCE_CAST ((o), GNC_TYPE_SPLIT, Split))
#define	GNC_SPLIT_CLASS(k)   (G_TYPE_CHECK_CLASS_CAST((k), GNC_TYPE_SPLIT, SplitClass))
#define	GNC_IS_SPLIT(o)   (G_TYPE_CHECK_INSTANCE_TYPE ((o), GNC_TYPE_SPLIT))
#define	GNC_IS_SPLIT_CLASS(k)   (G_TYPE_CHECK_CLASS_TYPE ((k), GNC_TYPE_SPLIT))
#define	GNC_SPLIT_GET_CLASS(o)   (G_TYPE_INSTANCE_GET_CLASS ((o), GNC_TYPE_SPLIT, SplitClass))
#define	xaccSplitGetGUID(X)   qof_entity_get_guid(QOF_INSTANCE(X))
#define	GNC_TYPE_TRANSACTION   (gnc_transaction_get_type ())
#define	GNC_TRANSACTION(o)   (G_TYPE_CHECK_INSTANCE_CAST ((o), GNC_TYPE_TRANSACTION, Transaction))
#define	GNC_TRANSACTION_CLASS(k)   (G_TYPE_CHECK_CLASS_CAST((k), GNC_TYPE_TRANSACTION, TransactionClass))
#define	GNC_IS_TRANSACTION(o)   (G_TYPE_CHECK_INSTANCE_TYPE ((o), GNC_TYPE_TRANSACTION))
#define	GNC_IS_TRANSACTION_CLASS(k)   (G_TYPE_CHECK_CLASS_TYPE ((k), GNC_TYPE_TRANSACTION))
#define	GNC_TRANSACTION_GET_CLASS(o)   (G_TYPE_INSTANCE_GET_CLASS ((o), GNC_TYPE_TRANSACTION, TransactionClass))
#define	GNC_IS_TRANS(obj)   GNC_IS_TRANSACTION(obj)
#define	GNC_TRANS(obj)   GNC_TRANSACTION(obj)
#define	RECONCILED_MATCH_TYPE   "reconciled-match"
#define	xaccTransGetBook(X)   qof_instance_get_book (QOF_INSTANCE(X))
#define	xaccTransGetGUID(X)   qof_entity_get_guid(QOF_INSTANCE(X))

Functions
GType	gnc_split_get_type (void)
gnc_numeric	xaccSplitConvertAmount (const Split *split, const Account *account)
GType	gnc_transaction_get_type (void)
void	xaccTransRecordPrice (Transaction *trans, PriceSource source)
	The xaccTransRecordPrice() method iterates through the splits and and record the non-currency equivalent prices in the price database. More...

Split Reconciled field values
These define the various reconciliations states a split can be in. If you change these be sure to change gnc-ui-util.c:gnc_get_reconciled_str() and associated functions
#define	CREC   'c'
	The Split has been cleared.
#define	YREC   'y'
	The Split has been reconciled.
#define	FREC   'f'
	frozen into accounting period
#define	NREC   'n'
	not reconciled or cleared
#define	VREC   'v'
	split is void

Split general getters/setters
Split *	xaccMallocSplit (QofBook *book)
	Constructor. More...
void	xaccSplitReinit (Split *split)
gboolean	xaccSplitDestroy (Split *split)
	Destructor. More...
void	xaccSplitCopyOnto (const Split *from_split, Split *to_split)
	This is really a helper for xaccTransCopyOnto. More...
QofBook *	xaccSplitGetBook (const Split *split)
	Returns the book of this split, i.e. More...
Account *	xaccSplitGetAccount (const Split *split)
	Returns the account of this split, which was set through xaccAccountInsertSplit(). More...
void	xaccSplitSetAccount (Split *s, Account *acc)
Transaction *	xaccSplitGetParent (const Split *split)
	Returns the parent transaction of the split. More...
void	xaccSplitSetParent (Split *split, Transaction *trans)
GNCLot *	xaccSplitGetLot (const Split *split)
	Returns the pointer to the debited/credited Lot where this split belongs to, or NULL if it doesn't belong to any. More...
void	xaccSplitSetLot (Split *split, GNCLot *lot)
	Assigns the split to a specific Lot.
void	xaccSplitSetMemo (Split *split, const char *memo)
	The memo is an arbitrary string associated with a split. More...
const char *	xaccSplitGetMemo (const Split *split)
	Returns the memo string. More...
void	xaccSplitSetOnlineID (Split *split, const char *id)
	The online_id is the OFX/HBCI "FITID" recorded on a split when it is imported. More...
const char *	xaccSplitGetOnlineID (const Split *split)
	Returns the split's online_id. More...
gboolean	xaccSplitHasOnlineID (const Split *split)
	Returns TRUE if the split has a non-empty online_id. More...
void	xaccSplitSetAction (Split *split, const char *action)
	The Action is an arbitrary user-assigned string. More...
const char *	xaccSplitGetAction (const Split *split)
	Returns the action string. More...

Split Date getters/setters
void	xaccSplitSetReconcile (Split *split, char reconciled_flag)
	Set the reconcile flag. More...
char	xaccSplitGetReconcile (const Split *split)
	Returns the value of the reconcile flag. More...
void	xaccSplitSetDateReconciledSecs (Split *split, time64 time)
	Set the date on which this split was reconciled by specifying the time as time64. More...
time64	xaccSplitGetDateReconciled (const Split *split)
	Retrieve the date when the Split was reconciled. More...

Split amount getters/setters
'value' vs. 'amount' of a Split: The 'value' is the amount of the transaction balancing commodity (i.e. currency) involved, 'amount' is the amount of the account's commodity involved.
void	xaccSplitSetAmount (Split *split, gnc_numeric amount)
	The xaccSplitSetAmount() method sets the amount in the account's commodity that the split should have. More...
gnc_numeric	xaccSplitGetAmount (const Split *split)
	Returns the amount of the split in the account's commodity. More...
void	xaccSplitSetValue (Split *split, gnc_numeric value)
	The xaccSplitSetValue() method sets the value of this split in the transaction's commodity. More...
gnc_numeric	xaccSplitGetValue (const Split *split)
	Returns the value of this split in the transaction's commodity. More...
void	xaccSplitSetSharePriceAndAmount (Split *split, gnc_numeric price, gnc_numeric amount)
	The xaccSplitSetSharePriceAndAmount() method will simultaneously update the share price and the number of shares. More...
gnc_numeric	xaccSplitGetSharePrice (const Split *split)
	Returns the price of the split, that is, the value divided by the amount. More...
void	xaccSplitSetBaseValue (Split *split, gnc_numeric value, const gnc_commodity *base_currency)
	Depending on the base_currency, set either the value or the amount of this split or both: If the base_currency is the transaction's commodity, set the value. More...
gnc_numeric	xaccSplitGetBaseValue (const Split *split, const gnc_commodity *base_currency)
	Depending on the base_currency, return either the value or the amount of this split: If the base_curreny is the transaction's commodity, return the value. More...
gnc_numeric	xaccSplitGetBalance (const Split *split)
	Returns the running balance up to and including the indicated split. More...
gnc_numeric	xaccSplitGetNoclosingBalance (const Split *split)
	The noclosing-balance is the currency-denominated balance of all transactions except 'closing' transactions. More...
gnc_numeric	xaccSplitGetClearedBalance (const Split *split)
	The cleared-balance is the currency-denominated balance of all transactions that have been marked as cleared or reconciled. More...
gnc_numeric	xaccSplitGetReconciledBalance (const Split *split)
	Returns the reconciled-balance of this split. More...

Split utility functions
gboolean	xaccSplitEqual (const Split *sa, const Split *sb, gboolean check_guids, gboolean check_balances, gboolean check_txn_splits)
	Equality. More...
Split *	xaccSplitLookup (const GncGUID *guid, QofBook *book)
	The xaccSplitLookup() subroutine will return the split associated with the given id, or NULL if there is no such split. More...
void	xaccSplitAddPeerSplit (Split *split, const Split *other_split, const time64 timestamp)
	Add a peer split to this split's lot-split list. More...
gboolean	xaccSplitHasPeers (const Split *split)
	Does this split have peers?
gboolean	xaccSplitIsPeerSplit (const Split *split, const Split *other_split)
	Report if a split is a peer of this one. More...
void	xaccSplitRemovePeerSplit (Split *split, const Split *other_split)
	Remove a peer split from this split's lot-split list. More...
void	xaccSplitMergePeerSplits (Split *split, const Split *other_split)
	Merge the other_split's peer splits into split's peers. More...
Split *	xaccSplitGetOtherSplit (const Split *split)
	The xaccSplitGetOtherSplit() is a convenience routine that returns the other of a pair of splits. More...
const char *	xaccSplitGetType (const Split *s)
	The xaccIsPeerSplit() is a convenience routine that returns TRUE (a non-zero value) if the two splits share a common parent transaction, else it returns FALSE (zero). More...
void	xaccSplitMakeStockSplit (Split *s)
	Mark a split to be of type stock split - after this, you shouldn't modify the value anymore, just the amount. More...
gint	xaccSplitOrder (const Split *sa, const Split *sb)
	The xaccSplitOrder(sa,sb) method is useful for sorting. More...
gint	xaccSplitOrderDateOnly (const Split *sa, const Split *sb)
int	xaccSplitCompareAccountFullNames (const Split *sa, const Split *sb)
	Compare two splits by full name of account. More...
int	xaccSplitCompareAccountCodes (const Split *sa, const Split *sb)
	Compare two splits by code of account. More...
int	xaccSplitCompareOtherAccountFullNames (const Split *sa, const Split *sb)
	Compare two splits by full name of the other account. More...
int	xaccSplitCompareOtherAccountCodes (const Split *sa, const Split *sb)
	Compare two splits by code of the other account. More...
char *	xaccSplitGetCorrAccountFullName (const Split *sa)
	These functions take a split, get the corresponding split on the "other side" of the transaction, and extract either the name or code of that split, reverting to returning a constant "Split" if the transaction has more than one split on the "other side". More...
const char *	xaccSplitGetCorrAccountName (const Split *sa)
	document me
const char *	xaccSplitGetCorrAccountCode (const Split *sa)
	document me
#define	xaccSplitLookupDirect(g, b)   xaccSplitLookup(&(g),b)

Split deprecated functions
void	xaccSplitSetSharePrice (Split *split, gnc_numeric price)

Split voiding
gnc_numeric	xaccSplitVoidFormerAmount (const Split *split)
	Returns the original pre-void amount of a split. More...
gnc_numeric	xaccSplitVoidFormerValue (const Split *split)
	Returns the original pre-void value of a split. More...

Split Parameter names
Note, if you want to get the equivalent of "ACCT_MATCH_ALL" you need to create a search on the following parameter list: SPLIT->SPLIT_TRANS->TRANS_SPLITLIST->SPLIT_ACCOUNT_GUID. If you do this, you might want to use the ACCOUNT_MATCH_ALL_TYPE as the override so the gnome-search dialog displays the right type.
#define	SPLIT_DATE_RECONCILED   "date-reconciled"
#define	SPLIT_BALANCE   "balance"
#define	SPLIT_CLEARED_BALANCE   "cleared-balance"
#define	SPLIT_RECONCILED_BALANCE   "reconciled-balance"
#define	SPLIT_MEMO   "memo"
#define	SPLIT_ACTION   "action"
#define	SPLIT_RECONCILE   "reconcile-flag"
#define	SPLIT_AMOUNT   "amount"
#define	SPLIT_SHARE_PRICE   "share-price"
#define	SPLIT_VALUE   "value"
#define	SPLIT_TYPE   "type"
#define	SPLIT_VOIDED_AMOUNT   "voided-amount"
#define	SPLIT_VOIDED_VALUE   "voided-value"
#define	SPLIT_LOT   "lot"
#define	SPLIT_TRANS   "trans"
#define	SPLIT_ACCOUNT   "account"
#define	SPLIT_ACCOUNT_GUID   "account-guid"
	for guid_match_all
#define	SPLIT_ACCT_FULLNAME   "acct-fullname"
#define	SPLIT_CORR_ACCT_NAME   "corr-acct-fullname"
#define	SPLIT_CORR_ACCT_CODE   "corr-acct-code"

Transaction Type field values
#define	TXN_TYPE_UNCACHED   '?' /** Transaction type not yet cached */
#define	TXN_TYPE_NONE   '\0'
	No transaction type.
#define	TXN_TYPE_INVOICE   'I'
	Transaction is an invoice.
#define	TXN_TYPE_PAYMENT   'P'
	Transaction is a payment.
#define	TXN_TYPE_LINK   'L'
	Transaction is a link between (invoice and payment) lots.

Transaction creation and editing
Transaction *	xaccMallocTransaction (QofBook *book)
	The xaccMallocTransaction() will malloc memory and initialize it. More...
void	xaccTransDestroy (Transaction *trans)
	Destroys a transaction. More...
Transaction *	xaccTransClone (const Transaction *t)
	The xaccTransClone() method will create a complete copy of an existing transaction.
Transaction *	xaccTransCloneNoKvp (const Transaction *t)
	The xaccTransCloneNoKvp() method will create a complete copy of an existing transaction except that the KVP slots will be empty.
gboolean	xaccTransEqual (const Transaction *ta, const Transaction *tb, gboolean check_guids, gboolean check_splits, gboolean check_balances, gboolean assume_ordered)
	Equality. More...
void	xaccTransBeginEdit (Transaction *trans)
	The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of its component splits. More...
void	xaccTransCommitEdit (Transaction *trans)
	The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are complete and should be made permanent. More...
void	xaccTransRollbackEdit (Transaction *trans)
	The xaccTransRollbackEdit() routine rejects all edits made, and sets the transaction back to where it was before the editing started. More...
gboolean	xaccTransIsOpen (const Transaction *trans)
	The xaccTransIsOpen() method returns TRUE if the transaction is open for editing. More...
Transaction *	xaccTransLookup (const GncGUID *guid, QofBook *book)
	The xaccTransLookup() subroutine will return the transaction associated with the given id, or NULL if there is no such transaction. More...
Transaction *	xaccTransCopyToClipBoard (const Transaction *from_trans)
	Copy a transaction to the 'clipboard' transaction using dupe_transaction. More...
void	xaccTransCopyOnto (const Transaction *from_trans, Transaction *to_trans)
	Copy a transaction to another using the function below without changing any account information.
void	xaccTransCopyFromClipBoard (const Transaction *from_trans, Transaction *to_trans, const Account *from_acc, Account *to_acc, gboolean no_date)
	This function explicitly must robustly handle some unusual input. More...
Split *	xaccTransFindSplitByAccount (const Transaction *trans, const Account *acc)
void	xaccTransScrubGains (Transaction *trans, Account *gain_acc)
	The xaccTransScrubGains() routine performs a number of cleanup functions on the indicated transaction, with the end-goal of setting up a consistent set of gains/losses for all the splits in the transaction. More...
guint	gnc_book_count_transactions (QofBook *book)
#define	xaccTransLookupDirect(g, b)   xaccTransLookup(&(g),b)

Transaction general getters/setters
gboolean	xaccTransUseTradingAccounts (const Transaction *trans)
	Determine whether this transaction should use commodity trading accounts.
void	xaccTransSortSplits (Transaction *trans)
	Sorts the splits in a transaction, putting the debits first, followed by the credits.
void	xaccTransSetTxnType (Transaction *trans, char type)
	Set the Transaction Type: note the type will be saved into the Transaction kvp property as a backward compatibility measure, for previous GnuCash versions whose xaccTransGetTxnType reads from the kvp slots. More...
char	xaccTransGetTxnType (Transaction *trans)
	Returns the Transaction Type: note this type will be derived from the transaction splits, returning TXN_TYPE_NONE, TXN_TYPE_INVOICE, TXN_TYPE_LINK, or TXN_TYPE_PAYMENT according to heuristics. More...
void	xaccTransSetNum (Transaction *trans, const char *num)
	Sets the transaction Number (or ID) field; rather than use this function directly, see 'gnc_set_num_action' in engine/engine-helpers.c & .h which takes a user-set book option for selecting the source for the num-cell (the transaction-number or the split-action field) in registers/reports into account automatically.
void	xaccTransSetDescription (Transaction *trans, const char *desc)
	Sets the transaction Description.
void	xaccTransSetDocLink (Transaction *trans, const char *doclink)
	Sets the transaction Document Link.
void	xaccTransSetNotes (Transaction *trans, const char *notes)
	Sets the transaction Notes. More...
const char *	xaccTransGetNum (const Transaction *trans)
	Gets the transaction Number (or ID) field; rather than use this function directly, see 'gnc_get_num_action' and 'gnc_get_action_num' in engine/engine-helpers.c & .h which takes a user-set book option for selecting the source for the num-cell (the transaction-number or the split-action field) in registers/reports into account automatically.
const char *	xaccTransGetDescription (const Transaction *trans)
	Gets the transaction Description.
const char *	xaccTransGetDocLink (const Transaction *trans)
	Gets the transaction Document Link.
const char *	xaccTransGetNotes (const Transaction *trans)
	Gets the transaction Notes. More...
void	xaccTransSetIsClosingTxn (Transaction *trans, gboolean is_closing)
	Sets whether or not this transaction is a "closing transaction".
gboolean	xaccTransGetIsClosingTxn (const Transaction *trans)
	Returns whether this transaction is a "closing transaction".
void	xaccTransClearSplits (Transaction *trans)
	Remove all splits from the transaction. More...
Split *	xaccTransGetSplit (const Transaction *trans, int i)
	Return a pointer to the indexed split in this transaction's split list. More...
int	xaccTransGetSplitIndex (const Transaction *trans, const Split *split)
	Inverse of xaccTransGetSplit()
SplitList *	xaccTransGetSplitList (const Transaction *trans)
	The xaccTransGetSplitList() method returns a GList of the splits in a transaction. More...
SplitList *	xaccTransGetPaymentAcctSplitList (const Transaction *trans)
	The xaccTransGetPaymentAcctSplitList() method returns a GList of the splits in a transaction that belong to an account which is considered a valid account for business payments. More...
SplitList *	xaccTransGetAPARAcctSplitList (const Transaction *trans, gboolean strict)
	The xaccTransGetAPARSplitList() method returns a GList of the splits in a transaction that belong to an AR or AP account. More...
gboolean	xaccTransStillHasSplit (const Transaction *trans, const Split *s)
Split *	xaccTransGetFirstPaymentAcctSplit (const Transaction *trans)
	The xaccTransGetFirstPaymentAcctSplit() method returns a pointer to the first split in this transaction that belongs to an account which is considered a valid account for business payments. More...
Split *	xaccTransGetFirstAPARAcctSplit (const Transaction *trans, gboolean strict)
	The xaccTransGetFirstPaymentAcctSplit() method returns a pointer to the first split in this transaction that belongs to an AR or AP account. More...
void	xaccTransSetReadOnly (Transaction *trans, const char *reason)
	Set the transaction to be ReadOnly by setting a non-NULL value as "reason". More...
void	xaccTransClearReadOnly (Transaction *trans)
const char *	xaccTransGetReadOnly (Transaction *trans)
	Returns a non-NULL value if this Transaction was marked as read-only with some specific "reason" text. More...
gboolean	xaccTransIsReadonlyByPostedDate (const Transaction *trans)
	Returns TRUE if this Transaction is read-only because its posted-date is older than the "auto-readonly" threshold of this book. More...
int	xaccTransCountSplits (const Transaction *trans)
	Returns the number of splits in this transaction. More...
gboolean	xaccTransHasReconciledSplits (const Transaction *trans)
	FIXME: document me.
gboolean	xaccTransHasReconciledSplitsByAccount (const Transaction *trans, const Account *account)
	FIXME: document me.
gboolean	xaccTransHasSplitsInState (const Transaction *trans, const char state)
	FIXME: document me.
gboolean	xaccTransHasSplitsInStateByAccount (const Transaction *trans, const char state, const Account *account)
	FIXME: document me.
gnc_commodity *	xaccTransGetCurrency (const Transaction *trans)
	Returns the valuation commodity of this transaction. More...
void	xaccTransSetCurrency (Transaction *trans, gnc_commodity *curr)
	Set the commodity of this transaction. More...
gnc_numeric	xaccTransGetImbalanceValue (const Transaction *trans)
	The xaccTransGetImbalanceValue() method returns the total value of the transaction. More...
MonetaryList *	xaccTransGetImbalance (const Transaction *trans)
	The xaccTransGetImbalance method returns a list giving the value of the transaction in each currency for which the balance is not zero. More...
gboolean	xaccTransIsBalanced (const Transaction *trans)
	Returns true if the transaction is balanced according to the rules currently in effect. More...
gnc_numeric	xaccTransGetAccountValue (const Transaction *trans, const Account *account)
	The xaccTransGetAccountValue() method returns the total value applied to a particular account. More...
gnc_numeric	xaccTransGetAccountAmount (const Transaction *trans, const Account *account)
	Same as xaccTransGetAccountValue, but uses the Account's commodity. More...
gnc_numeric	xaccTransGetAccountConvRate (const Transaction *txn, const Account *acc)
gnc_numeric	xaccTransGetAccountBalance (const Transaction *trans, const Account *account)
	Get the account balance for the specified account after the last split in the specified transaction. More...
int	xaccTransOrder (const Transaction *ta, const Transaction *tb)
	The xaccTransOrder(ta,tb) method is useful for sorting. More...
int	xaccTransOrder_num_action (const Transaction *ta, const char *actna, const Transaction *tb, const char *actnb)
	The xaccTransOrder_num_action(ta,actna,tb,actnb) method is useful for sorting. More...
#define	xaccTransAppendSplit(t, s)   xaccSplitSetParent((s), (t))
	Add a split to the transaction. More...

Transaction date setters/getters
void	xaccTransSetDate (Transaction *trans, int day, int mon, int year)
	The xaccTransSetDate() method does the same thing as xaccTransSetDate[Posted]Secs(), but takes a convenient day-month-year format. More...
void	xaccTransSetDatePostedGDate (Transaction *trans, GDate date)
	This method modifies posted date of the transaction, specified by a GDate. More...
void	xaccTransSetDatePostedSecs (Transaction *trans, time64 time)
	The xaccTransSetDatePostedSecs() method will modify the posted date of the transaction, specified by a time64 (see ctime(3)). More...
void	xaccTransSetDatePostedSecsNormalized (Transaction *trans, time64 time)
	This function sets the posted date of the transaction, specified by a time64 (see ctime(3)). More...
void	xaccTransSetDateEnteredSecs (Transaction *trans, time64 time)
	Modify the date of when the transaction was entered. More...
void	xaccTransSetDateDue (Transaction *trans, time64 time)
	Dates and txn-type for A/R and A/P "invoice" postings.
time64	xaccTransGetDate (const Transaction *trans)
	Retrieve the posted date of the transaction. More...
time64	xaccTransRetDatePosted (const Transaction *trans)
	Retrieve the posted date of the transaction. More...
GDate	xaccTransGetDatePostedGDate (const Transaction *trans)
	Retrieve the posted date of the transaction. More...
time64	xaccTransGetDateEntered (const Transaction *trans)
	Retrieve the date of when the transaction was entered. More...
time64	xaccTransRetDateEntered (const Transaction *trans)
	Retrieve the date of when the transaction was entered. More...
time64	xaccTransRetDateDue (const Transaction *trans)
	Dates and txn-type for A/R and A/P "invoice" postings.

Transaction voiding
void	xaccTransVoid (Transaction *transaction, const char *reason)
	xaccTransVoid voids a transaction. More...
void	xaccTransUnvoid (Transaction *transaction)
	xaccTransUnvoid restores a voided transaction to its original state. More...
Transaction *	xaccTransReverse (Transaction *transaction)
	xaccTransReverse creates a Transaction that reverses the given transaction by inverting all the numerical values in the given transaction. More...
Transaction *	xaccTransGetReversedBy (const Transaction *trans)
	Returns the transaction that reversed the given transaction. More...
gboolean	xaccTransGetVoidStatus (const Transaction *transaction)
	Retrieve information on whether or not a transaction has been voided. More...
const char *	xaccTransGetVoidReason (const Transaction *transaction)
	Returns the user supplied textual reason why a transaction was voided. More...
time64	xaccTransGetVoidTime (const Transaction *tr)
	Returns the time that a transaction was voided. More...

Transaction Parameter names
#define	TRANS_KVP   "kvp"
#define	TRANS_NUM   "num"
#define	TRANS_DESCRIPTION   "desc"
#define	TRANS_DATE_ENTERED   "date-entered"
#define	TRANS_DATE_POSTED   "date-posted"
#define	TRANS_DATE_DUE   "date-due"
#define	TRANS_IMBALANCE   "trans-imbalance"
#define	TRANS_IS_BALANCED   "trans-balanced?"
#define	TRANS_IS_CLOSING   "trans-is-closing?"
#define	TRANS_NOTES   "notes"
#define	TRANS_DOCLINK   "doclink"
#define	TRANS_TYPE   "type"
#define	TRANS_VOID_STATUS   "void-p"
#define	TRANS_VOID_REASON   "void-reason"
#define	TRANS_VOID_TIME   "void-time"
#define	TRANS_SPLITLIST   "split-list" /* for guid_match_all */

Detailed Description

A good overview of transactions, splits and accounts can be found in the texinfo documentation, together with an overview of how to use this API.

Splits, or "Ledger Entries" are the fundamental accounting units. Each Split consists of an amount (number of dollar bills, number of shares, etc.), the value of that amount expressed in a (possibly) different currency than the amount, a Memo, a pointer to the parent Transaction, a pointer to the debited Account, a reconciled flag and timestamp, an "Action" field, and a key-value frame which can store arbitrary data.

Transactions embody the notion of "double entry" accounting. A Transaction consists of a date, a description, an ID number, a list of one or more Splits, and a key-value frame. The transaction also specifies the currency with which all of the splits will be valued. When double-entry rules are enforced, the sum total value of the splits are zero. If there are only two splits, then the value of one must be positive, the other negative: this denotes that one account is debited, and another is credited by an equal amount. By forcing the value of the splits to always 'add up' to zero, we can guarantee that the balances of the accounts are always correctly balanced.

The engine does not enforce double-entry accounting, but provides an API to enable user-code to find unbalanced transactions and 'repair' them so that they are in balance.

Note the sum of the values of Splits in a Transaction is always computed with respect to a currency; thus splits can be balanced even when they are in different currencies, as long as they share a common currency. This feature allows currency-trading accounts to be established.

Every Split must point to its parent Transaction, and that Transaction must in turn include that Split in the Transaction's list of Splits. A Split can belong to at most one Transaction. These relationships are enforced by the engine. The engine user cannot accidentally destroy this relationship as long as they stick to using the API and never access internal structures directly.

Splits are grouped into Accounts which are also known as "Ledgers" in accounting practice. Each Account consists of a list of Splits that debit that Account. To ensure consistency, if a Split points to an Account, then the Account must point to the Split, and vice-versa. A Split can belong to at most one Account. Besides merely containing a list of Splits, the Account structure also gives the Account a name, a code number, description and notes fields, a key-value frame, a pointer to the commodity that is used for all splits in this account. The commodity can be the name of anything traded and tradable: a stock (e.g. "IBM", "McDonald's"), a currency (e.g. "USD", "GBP"), or anything added to the commodity table.

Accounts can be arranged in a hierarchical tree. The nodes of the tree are called "Account Groups". By accounting convention, the value of an Account is equal to the value of all of its Splits plus the value of all of its sub-Accounts.

Macro Definition Documentation

xaccSplitGetGUID

#define xaccSplitGetGUID

(

X

)

qof_entity_get_guid(QOF_INSTANCE(X))

Deprecated:

Definition at line 571 of file Split.h.

xaccTransAppendSplit

#define xaccTransAppendSplit	(		t,
			s
	)		xaccSplitSetParent((s), (t))

Add a split to the transaction.

The xaccTransAppendSplit() method will append the indicated split to the collection of splits in this transaction.

Note

If the split is already a part of another transaction, it will be removed from that transaction first.

Definition at line 380 of file Transaction.h.

xaccTransGetBook

#define xaccTransGetBook

(

X

)

qof_instance_get_book (QOF_INSTANCE(X))

Deprecated:

Definition at line 785 of file Transaction.h.

xaccTransGetGUID

#define xaccTransGetGUID

(

X

)

qof_entity_get_guid(QOF_INSTANCE(X))

Deprecated:

Definition at line 787 of file Transaction.h.

Function Documentation

gnc_book_count_transactions()

guint gnc_book_count_transactions

(

QofBook *

book

)

Warning

XXX FIXME gnc_book_count_transactions is a utility function, probably needs to be moved to a utility file somewhere.

Definition at line 2504 of file Transaction.cpp.

{
    guint count = 0;
    xaccAccountTreeForEachTransaction(gnc_book_get_root_account(book),
                                      counter_thunk, (void*)&count);
    return count;
}

xaccMallocSplit()

Split* xaccMallocSplit

(

QofBook *

book

)

Constructor.

Definition at line 37 of file gmock-Split.cpp.

{
    SCOPED_TRACE("");
    QofMockBook* mockbook = qof_mockbook(book);
    return mockbook ? mockbook->malloc_split() : nullptr;
}

xaccMallocTransaction()

Transaction* xaccMallocTransaction

(

QofBook *

book

)

The xaccMallocTransaction() will malloc memory and initialize it.

Once created, it is usually unsafe to merely "free" this memory; the xaccTransDestroy() method should be called.

Definition at line 485 of file Transaction.cpp.

{
    Transaction *trans;

    g_return_val_if_fail (book, nullptr);

    trans = GNC_TRANSACTION(g_object_new(GNC_TYPE_TRANSACTION, nullptr));
    xaccInitTransaction (trans, book);
    qof_event_gen (&trans->inst, QOF_EVENT_CREATE, nullptr);

    return trans;
}

xaccSplitAddPeerSplit()

void xaccSplitAddPeerSplit	(	Split *	split,
		const Split *	other_split,
		const time64	timestamp
	)

Add a peer split to this split's lot-split list.

Parameters

other_split	The split whose guid to add
timestamp	The time to be recorded for the split.

Definition at line 2037 of file Split.cpp.

{
    const GncGUID* guid;

    g_return_if_fail (split != nullptr);
    g_return_if_fail (other_split != nullptr);

    guid = qof_instance_get_guid (QOF_INSTANCE (other_split));
    xaccTransBeginEdit (split->parent);
    qof_instance_kvp_add_guid (QOF_INSTANCE (split), "lot-split",
                               gnc_time(nullptr), "peer_guid", guid_copy(guid));
    mark_split (split);
    qof_instance_set_dirty (QOF_INSTANCE (split));
    xaccTransCommitEdit (split->parent);
}

xaccSplitCompareAccountCodes()

int xaccSplitCompareAccountCodes	(	const Split *	sa,
		const Split *	sb
	)

Compare two splits by code of account.

Returns similar to strcmp.

Definition at line 1677 of file Split.cpp.

{
    Account *aa, *ab;
    if (!sa && !sb) return 0;
    if (!sa) return -1;
    if (!sb) return 1;

    aa = sa->acc;
    ab = sb->acc;

    return g_strcmp0(xaccAccountGetCode(aa), xaccAccountGetCode(ab));
}

xaccSplitCompareAccountFullNames()

int xaccSplitCompareAccountFullNames	(	const Split *	sa,
		const Split *	sb
	)

Compare two splits by full name of account.

Returns similar to strcmp.

Definition at line 1653 of file Split.cpp.

{
    Account *aa, *ab;
    if (sa == sb) return 0;
    if (!sa) return -1;
    if (!sb) return 1;

    aa = sa->acc;
    ab = sb->acc;
    if (aa == ab) return 0;

    auto path_a = gnc_account_get_all_parents (aa);
    auto path_b = gnc_account_get_all_parents (ab);
    auto mismatch_pair = std::mismatch (path_a.rbegin(), path_a.rend(),
                                        path_b.rbegin(), path_b.rend());

    return mismatch_pair.first == path_a.rend() ? -1
        : mismatch_pair.second == path_b.rend() ? 1
        : g_utf8_collate (xaccAccountGetName (*mismatch_pair.first),
                          xaccAccountGetName (*mismatch_pair.second));
}

xaccSplitCompareOtherAccountCodes()

int xaccSplitCompareOtherAccountCodes	(	const Split *	sa,
		const Split *	sb
	)

Compare two splits by code of the other account.

Returns similar to strcmp. This function attempts to find the split on the other side of a transaction and compare on it.

Definition at line 1712 of file Split.cpp.

{
    const char *ca, *cb;
    if (!sa && !sb) return 0;
    if (!sa) return -1;
    if (!sb) return 1;

    ca = xaccSplitGetCorrAccountCode(sa);
    cb = xaccSplitGetCorrAccountCode(sb);
    return g_strcmp0(ca, cb);
}

xaccSplitCompareOtherAccountFullNames()

int xaccSplitCompareOtherAccountFullNames	(	const Split *	sa,
		const Split *	sb
	)

Compare two splits by full name of the other account.

Returns similar to strcmp. This function attempts to find the split on the other side of a transaction and compare on it.

Definition at line 1691 of file Split.cpp.

{
    char *ca, *cb;
    int retval;
    if (!sa && !sb) return 0;
    if (!sa) return -1;
    if (!sb) return 1;

    /* doesn't matter what separator we use
     * as long as they are the same
     */

    ca = xaccSplitGetCorrAccountFullName(sa);
    cb = xaccSplitGetCorrAccountFullName(sb);
    retval = g_strcmp0(ca, cb);
    g_free(ca);
    g_free(cb);
    return retval;
}

xaccSplitCopyOnto()

void xaccSplitCopyOnto	(	const Split *	from_split,
		Split *	to_split
	)

This is really a helper for xaccTransCopyOnto.

It doesn't reparent the 'to' split to from's transaction, because xaccTransCopyOnto is responsible for parenting the split to the correct transaction. Also, from's parent transaction may not even be a valid transaction, so this function may not modify anything about 'from' or from's transaction.

Definition at line 640 of file Split.cpp.

{
    if (!from_split || !to_split) return;
    xaccTransBeginEdit (to_split->parent);

    xaccSplitSetMemo(to_split, xaccSplitGetMemo(from_split));
    xaccSplitSetAction(to_split, xaccSplitGetAction(from_split));
    xaccSplitSetAmount(to_split, xaccSplitGetAmount(from_split));
    xaccSplitSetValue(to_split, xaccSplitGetValue(from_split));
    /* Setting the account is okay here because, even though the from
       split might not really belong to the account it claims to,
       setting the account won't cause any event involving from. */
    xaccSplitSetAccount(to_split, xaccSplitGetAccount(from_split));
    /* N.B. Don't set parent. */

    qof_instance_set_dirty(QOF_INSTANCE(to_split));
    xaccTransCommitEdit(to_split->parent);
}

xaccSplitDestroy()

gboolean xaccSplitDestroy

(

Split *

split

)

Destructor.

The xaccSplitDestroy() method will update its parent account and transaction in a consistent manner, resulting in the complete unlinking of the split, and the freeing of its associated memory. The goal of this routine is to perform the removal and destruction of the split in an atomic fashion, with no chance of accidentally leaving the accounting structure out-of-balance or otherwise inconsistent.

It begins and commits an edit on the transaction, so if after the split is removed the transaction has no more splits and if is not open it too will be destroyed, as it will if the outer edits are committed without adding transactions.

Returns

TRUE upon successful deletion of the split. FALSE when the parenting Transaction is a read-only one.

Definition at line 1471 of file Split.cpp.

{
    Account *acc;
    Transaction *trans;
    GncEventData ed;

    if (!split) return TRUE;

    acc = split->acc;
    trans = split->parent;
    if (acc && !qof_instance_get_destroying(acc)
        && !qof_instance_get_destroying(trans)
        && xaccTransGetReadOnly(trans))
        return FALSE;

    xaccTransBeginEdit(trans);
    ed.node = split;
    ed.idx = xaccTransGetSplitIndex(trans, split);
    qof_instance_set_dirty(QOF_INSTANCE(split));
    qof_instance_set_destroying(split, TRUE);
    qof_event_gen(&trans->inst, GNC_EVENT_ITEM_REMOVED, &ed);
    xaccTransCommitEdit(trans);

    return TRUE;
}

xaccSplitEqual()

gboolean xaccSplitEqual	(	const Split *	sa,
		const Split *	sb,
		gboolean	check_guids,
		gboolean	check_balances,
		gboolean	check_txn_splits
	)

Equality.

Parameters

sa	First split to compare
sb	Second split to compare
check_guids	If TRUE, try a guid_equal() on the GUIDs of both splits if their pointers are not equal in the first place.
check_balances	If TRUE, compare balances between the two splits. Balances are recalculated whenever a split is added or removed from an account, so YMMV on whether this should be set.
check_txn_splits	If the pointers are not equal, but everything else so far is equal (including memo, amount, value, kvp), then, when comparing the parenting transactions with xaccTransEqual(), set its argument check_splits to be TRUE.

Definition at line 803 of file Split.cpp.

{
    gboolean same_book;

    if (!sa && !sb) return TRUE; /* Arguable. FALSE is better, methinks */

    if (!sa || !sb)
    {
        PINFO ("one is nullptr");
        return FALSE;
    }

    if (sa == sb) return TRUE;

    same_book = qof_instance_get_book(QOF_INSTANCE(sa)) == qof_instance_get_book(QOF_INSTANCE(sb));

    if (check_guids)
    {
        if (qof_instance_guid_compare(sa, sb) != 0)
        {
            PINFO ("GUIDs differ");
            return FALSE;
        }
    }

    /* If the same book, since these strings are cached we can just use pointer equality */
    if ((same_book && sa->memo != sb->memo) || (!same_book && g_strcmp0(sa->memo, sb->memo) != 0))
    {
        PINFO ("memos differ: (%p)%s vs (%p)%s",
               sa->memo, sa->memo, sb->memo, sb->memo);
        return FALSE;
    }

    if ((same_book && sa->action != sb->action) || (!same_book && g_strcmp0(sa->action, sb->action) != 0))
    {
        PINFO ("actions differ: %s vs %s", sa->action, sb->action);
        return FALSE;
    }

    if (qof_instance_compare_kvp (QOF_INSTANCE (sa), QOF_INSTANCE (sb)) != 0)
    {
        char *frame_a;
        char *frame_b;

        frame_a = qof_instance_kvp_as_string (QOF_INSTANCE (sa));
        frame_b = qof_instance_kvp_as_string (QOF_INSTANCE (sb));

        PINFO ("kvp frames differ:\n%s\n\nvs\n\n%s", frame_a, frame_b);

        g_free (frame_a);
        g_free (frame_b);

        return FALSE;
    }

    if (sa->reconciled != sb->reconciled)
    {
        PINFO ("reconcile flags differ: %c vs %c", sa->reconciled, sb->reconciled);
        return FALSE;
    }

    if (sa->date_reconciled != sb->date_reconciled)
    {
        PINFO ("reconciled date differs");
        return FALSE;
    }

    if (!gnc_numeric_eq(xaccSplitGetAmount (sa), xaccSplitGetAmount (sb)))
    {
        char *str_a;
        char *str_b;

        str_a = gnc_numeric_to_string (xaccSplitGetAmount (sa));
        str_b = gnc_numeric_to_string (xaccSplitGetAmount (sb));

        PINFO ("amounts differ: %s vs %s", str_a, str_b);

        g_free (str_a);
        g_free (str_b);

        return FALSE;
    }

    if (!gnc_numeric_eq(xaccSplitGetValue (sa), xaccSplitGetValue (sb)))
    {
        char *str_a;
        char *str_b;

        str_a = gnc_numeric_to_string (xaccSplitGetValue (sa));
        str_b = gnc_numeric_to_string (xaccSplitGetValue (sb));

        PINFO ("values differ: %s vs %s", str_a, str_b);

        g_free (str_a);
        g_free (str_b);

        return FALSE;
    }

    if (check_balances)
    {
        if (!xaccSplitEqualCheckBal ("", sa->balance, sb->balance))
            return FALSE;
        if (!xaccSplitEqualCheckBal ("cleared ", sa->cleared_balance,
                                     sb->cleared_balance))
            return FALSE;
        if (!xaccSplitEqualCheckBal ("reconciled ", sa->reconciled_balance,
                                     sb->reconciled_balance))
            return FALSE;
        if (!xaccSplitEqualCheckBal ("noclosing ", sa->noclosing_balance,
                                     sb->noclosing_balance))
            return FALSE;
    }

    if (!xaccTransEqual(sa->parent, sb->parent, check_guids, check_txn_splits,
                        check_balances, FALSE))
    {
        PINFO ("transactions differ");
        return FALSE;
    }

    return TRUE;
}

xaccSplitGetAccount()

Account* xaccSplitGetAccount

(

const Split *

split

)

Returns the account of this split, which was set through xaccAccountInsertSplit().

Definition at line 53 of file gmock-Split.cpp.

{
    SCOPED_TRACE("");
    auto mocksplit = gnc_mocksplit(split);
    return mocksplit ? mocksplit->get_account() : nullptr;
}

xaccSplitGetAction()

const char* xaccSplitGetAction

(

const Split *

split

)

Returns the action string.

Rather than use this function directly, see 'gnc_get_num_action' and 'gnc_get_action_num'in engine/engine-helpers.c & .h which takes a user-set book option for selecting the source for the num-cell (the transaction-number or the split-action field) in registers/reports into account automatically

Definition at line 151 of file gmock-Split.cpp.

{
    SCOPED_TRACE("");
    auto mocksplit = gnc_mocksplit(split);
    return mocksplit ? mocksplit->get_action() : "";
}

xaccSplitGetAmount()

gnc_numeric xaccSplitGetAmount

(

const Split *

split

)

Returns the amount of the split in the account's commodity.

Note that for cap-gains splits, this is slaved to the transaction that is causing the gains to occur.

Definition at line 69 of file gmock-Split.cpp.

{
    SCOPED_TRACE("");
    auto mocksplit = gnc_mocksplit(split);
    return mocksplit ? mocksplit->get_amount() : gnc_numeric_zero();
}

xaccSplitGetBalance()

gnc_numeric xaccSplitGetBalance

(

const Split *

split

)

Returns the running balance up to and including the indicated split.

The balance is the currency-denominated balance. For accounts with non-unit share prices, it is correctly adjusted for share prices.

Returns the running balance up to & including the indicated split.

Definition at line 1296 of file Split.cpp.

{
    return s ? s->balance : gnc_numeric_zero();
}

xaccSplitGetBaseValue()

gnc_numeric xaccSplitGetBaseValue	(	const Split *	split,
		const gnc_commodity *	base_currency
	)

Depending on the base_currency, return either the value or the amount of this split: If the base_curreny is the transaction's commodity, return the value.

If it is the account's commodity, return the amount. If it is neither print a warning message and return gnc_numeric_zero().

Definition at line 1375 of file Split.cpp.

{
    if (!s || !s->acc || !s->parent) return gnc_numeric_zero();

    /* be more precise -- the value depends on the currency we want it
     * expressed in.  */
    if (gnc_commodity_equiv(xaccTransGetCurrency(s->parent), base_currency))
        return xaccSplitGetValue(s);
    if (gnc_commodity_equiv(xaccAccountGetCommodity(s->acc), base_currency))
        return xaccSplitGetAmount(s);

    PERR ("inappropriate base currency %s "
          "given split currency=%s and commodity=%s\n",
          gnc_commodity_get_printname(base_currency),
          gnc_commodity_get_printname(xaccTransGetCurrency (s->parent)),
          gnc_commodity_get_printname(xaccAccountGetCommodity(s->acc)));
    return gnc_numeric_zero();
}

xaccSplitGetBook()

QofBook* xaccSplitGetBook

(

const Split *

split

)

Returns the book of this split, i.e.

the entity where this split is stored.

Definition at line 45 of file gmock-Split.cpp.

{
    SCOPED_TRACE("");
    auto mocksplit = gnc_mocksplit(split);
    return mocksplit ? mocksplit->get_book() : nullptr;
}

xaccSplitGetClearedBalance()

gnc_numeric xaccSplitGetClearedBalance

(

const Split *

split

)

The cleared-balance is the currency-denominated balance of all transactions that have been marked as cleared or reconciled.

It is correctly adjusted for price fluctuations.

Returns the running balance up to & including the indicated split.

Definition at line 1308 of file Split.cpp.

{
    return s ? s->cleared_balance : gnc_numeric_zero();
}

xaccSplitGetCorrAccountFullName()

char* xaccSplitGetCorrAccountFullName

(

const Split *

sa

)

These functions take a split, get the corresponding split on the "other side" of the transaction, and extract either the name or code of that split, reverting to returning a constant "Split" if the transaction has more than one split on the "other side".

These were added for the transaction report, and is in C because the code was already written in C for the above functions and duplication is silly.

Note that this will only return a real value in case of a two-split transaction as that is the only situation in which a reliable value can be returned. In other situations "-- Split Transaction --" will be returned as Account Name or "Split" for Account Code.

Definition at line 1620 of file Split.cpp.

{
    static const char *split_const = nullptr;
    const Split *other_split;

    if (!get_corr_account_split(sa, &other_split))
    {
        if (!split_const)
            split_const = _("-- Split Transaction --");

        return g_strdup(split_const);
    }
    return gnc_account_get_full_name(other_split->acc);
}

xaccSplitGetDateReconciled()

time64 xaccSplitGetDateReconciled

(

const Split *

split

)

Retrieve the date when the Split was reconciled.

Definition at line 1824 of file Split.cpp.

{
    return split ? split->date_reconciled : 0;
}

xaccSplitGetLot()

GNCLot* xaccSplitGetLot

(

const Split *

split

)

Returns the pointer to the debited/credited Lot where this split belongs to, or NULL if it doesn't belong to any.

Definition at line 1885 of file Split.cpp.

{
    return split ? split->lot : nullptr;
}

xaccSplitGetMemo()

const char* xaccSplitGetMemo

(

const Split *

split

)

Returns the memo string.

Definition at line 99 of file gmock-Split.cpp.

{
    SCOPED_TRACE("");
    auto mocksplit = gnc_mocksplit(split);
    return mocksplit ? mocksplit->get_memo() : "";
}

xaccSplitGetNoclosingBalance()

gnc_numeric xaccSplitGetNoclosingBalance

(

const Split *

split

)

The noclosing-balance is the currency-denominated balance of all transactions except 'closing' transactions.

It is correctly adjusted for price fluctuations.

Returns the running balance up to & including the indicated split.

Definition at line 1302 of file Split.cpp.

{
    return s ? s->noclosing_balance : gnc_numeric_zero();
}

xaccSplitGetOnlineID()

const char* xaccSplitGetOnlineID

(

const Split *

split

)

Returns the split's online_id.

The returned string is owned by the split and must NOT be freed; it is valid until the online_id is changed or the split is destroyed. Returns NULL if no online_id is set.

Definition at line 114 of file gmock-Split.cpp.

{
    SCOPED_TRACE("");
    auto mocksplit = gnc_mocksplit(split);
    return mocksplit ? mocksplit->get_online_id() : nullptr;
}

xaccSplitGetOtherSplit()

Split* xaccSplitGetOtherSplit

(

const Split *

split

)

The xaccSplitGetOtherSplit() is a convenience routine that returns the other of a pair of splits.

If there are more than two splits, it returns NULL.

Definition at line 159 of file gmock-Split.cpp.

{
    SCOPED_TRACE("");
    auto mocksplit = gnc_mocksplit(split);
    return mocksplit ? mocksplit->get_other_split() : nullptr;
}

xaccSplitGetParent()

Transaction* xaccSplitGetParent

(

const Split *

split

)

Returns the parent transaction of the split.

Definition at line 167 of file gmock-Split.cpp.

{
    SCOPED_TRACE("");
    auto mocksplit = gnc_mocksplit(split);
    return mocksplit ? mocksplit->get_parent() : nullptr;
}

xaccSplitGetReconcile()

char xaccSplitGetReconcile

(

const Split *

split

)

Returns the value of the reconcile flag.

Definition at line 129 of file gmock-Split.cpp.

{
    SCOPED_TRACE("");
    auto mocksplit = gnc_mocksplit(split);
    return mocksplit ? mocksplit->get_reconcile() : VREC;
}

xaccSplitGetReconciledBalance()

gnc_numeric xaccSplitGetReconciledBalance

(

const Split *

split

)

Returns the reconciled-balance of this split.

The reconciled-balance is the currency-denominated balance of all transactions that have been marked as reconciled.

Returns the running balance up to & including the indicated split.

Definition at line 1314 of file Split.cpp.

{
    return s ? s->reconciled_balance : gnc_numeric_zero();
}

xaccSplitGetSharePrice()

gnc_numeric xaccSplitGetSharePrice

(

const Split *

split

)

Returns the price of the split, that is, the value divided by the amount.

If the amount is zero, returns a gnc_numeric of value one.

Definition at line 1960 of file Split.cpp.

{
    gnc_numeric amt, val, price;
    if (!split) return gnc_numeric_create(0, 1);


    /* if amount == 0, return 0
     * otherwise return value/amount
     */

    amt = xaccSplitGetAmount(split);
    val = xaccSplitGetValue(split);
    if (gnc_numeric_zero_p(amt))
        return gnc_numeric_create(0, 1);

    price = gnc_numeric_div(val, amt,
                            GNC_DENOM_AUTO,
                            GNC_HOW_RND_ROUND_HALF_UP);

    /* During random checks we can get some very weird prices.  Let's
     * handle some overflow and other error conditions by returning
     * zero.  But still print an error to let us know it happened.
     */
    if (gnc_numeric_check(price))
    {
        PERR("Computing share price failed (%d): [ %" G_GINT64_FORMAT " / %"
             G_GINT64_FORMAT " ] / [ %" G_GINT64_FORMAT " / %" G_GINT64_FORMAT " ]",
             gnc_numeric_check(price), val.num, val.denom, amt.num, amt.denom);
        return gnc_numeric_create(0, 1);
    }

    return price;
}

xaccSplitGetType()

const char* xaccSplitGetType

(

const Split *

s

)

The xaccIsPeerSplit() is a convenience routine that returns TRUE (a non-zero value) if the two splits share a common parent transaction, else it returns FALSE (zero).

gboolean xaccIsPeerSplit (const Split *split_1, const Split *split_2); Returns the split type, which is either the string "normal", or "stock-split" for a split from a stock split (pun intended? :-).

Definition at line 2004 of file Split.cpp.

{
    if (!s) return nullptr;

    auto type{qof_instance_get_path_kvp<const char*> (QOF_INSTANCE(s), {"split-type"})};

    if (!type || !g_strcmp0 (*type, split_type_normal))
        return split_type_normal;

    if (!g_strcmp0 (*type, split_type_stock_split))
        return split_type_stock_split;

    PERR ("unexpected split-type %s, reset to normal.", *type);
    return split_type_normal;
}

xaccSplitGetValue()

gnc_numeric xaccSplitGetValue

(

const Split *

split

)

Returns the value of this split in the transaction's commodity.

Note that for cap-gains splits, this is slaved to the transaction that is causing the gains to occur.

Definition at line 84 of file gmock-Split.cpp.

{
    SCOPED_TRACE("");
    auto mocksplit = gnc_mocksplit(split);
    return mocksplit ? mocksplit->get_value() : gnc_numeric_zero();
}

xaccSplitHasOnlineID()

gboolean xaccSplitHasOnlineID

(

const Split *

split

)

Returns TRUE if the split has a non-empty online_id.

Definition at line 1928 of file Split.cpp.

{
    auto id = xaccSplitGetOnlineID (split);
    return (id && *id);
}

xaccSplitIsPeerSplit()

gboolean xaccSplitIsPeerSplit	(	const Split *	split,
		const Split *	other_split
	)

Report if a split is a peer of this one.

Parameters

other_split

The split to test for being a peer of this one.

Returns

: True if other_split is registered as a peer of this one.

Definition at line 2061 of file Split.cpp.

{
    const GncGUID* guid;

    g_return_val_if_fail (split != nullptr, FALSE);
    g_return_val_if_fail (other_split != nullptr, FALSE);

    guid = qof_instance_get_guid (QOF_INSTANCE (other_split));
    return qof_instance_kvp_has_guid (QOF_INSTANCE (split), "lot-split",
                                      "peer_guid", guid);
}

xaccSplitLookup()

Split* xaccSplitLookup	(	const GncGUID *	guid,
		QofBook *	book
	)

The xaccSplitLookup() subroutine will return the split associated with the given id, or NULL if there is no such split.

Definition at line 1072 of file Split.cpp.

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

xaccSplitMakeStockSplit()

void xaccSplitMakeStockSplit

(

Split *

s

)

Mark a split to be of type stock split - after this, you shouldn't modify the value anymore, just the amount.

Definition at line 2023 of file Split.cpp.

{
    xaccTransBeginEdit (s->parent);

    s->value = gnc_numeric_zero();
    qof_instance_set_path_kvp<const char*> (QOF_INSTANCE(s), g_strdup(split_type_stock_split),
                                            {"split-type"});
    SET_GAINS_VDIRTY(s);
    mark_split(s);
    qof_instance_set_dirty(QOF_INSTANCE(s));
    xaccTransCommitEdit(s->parent);
}

xaccSplitMergePeerSplits()

void xaccSplitMergePeerSplits	(	Split *	split,
		const Split *	other_split
	)

Merge the other_split's peer splits into split's peers.

Parameters

other_split

The split donating the peer splits.

Definition at line 2091 of file Split.cpp.

{
    xaccTransBeginEdit (split->parent);
    qof_instance_kvp_merge_guids (QOF_INSTANCE (split),
                                  QOF_INSTANCE (other_split), "lot-split");
    mark_split (split);
    qof_instance_set_dirty (QOF_INSTANCE (split));
    xaccTransCommitEdit (split->parent);
}

xaccSplitOrder()

gint xaccSplitOrder	(	const Split *	sa,
		const Split *	sb
	)

The xaccSplitOrder(sa,sb) method is useful for sorting.

if sa and sb have different transactions, return their xaccTransOrder return a negative value if split sa has a smaller currency-value than sb, return a positive value if split sa has a larger currency-value than sb, return a negative value if split sa has a smaller share-price than sb, return a positive value if split sa has a larger share-price than sb, then compares memo and action using the strcmp() c-library routine, returning what strcmp would return. Then it compares the reconciled flags, then the reconciled dates, Finally, it returns zero if all of the above match.

Definition at line 1501 of file Split.cpp.

{
    int retval;
    int comp;
    const char *da, *db;
    gboolean action_for_num;

    if (sa == sb) return 0;
    /* nothing is always less than something */
    if (!sa) return -1;
    if (!sb) return +1;

    /* sort in transaction order, but use split action rather than trans num
     * according to book option */
    action_for_num = qof_book_use_split_action_for_num_field
        (xaccSplitGetBook (sa));
    if (action_for_num)
        retval = xaccTransOrder_num_action (sa->parent, sa->action,
                                            sb->parent, sb->action);
    else
        retval = xaccTransOrder (sa->parent, sb->parent);
    if (retval) return retval;

    /* otherwise, sort on memo strings */
    da = sa->memo ? sa->memo : "";
    db = sb->memo ? sb->memo : "";
    retval = g_utf8_collate (da, db);
    if (retval)
        return retval;

    /* otherwise, sort on action strings */
    da = sa->action ? sa->action : "";
    db = sb->action ? sb->action : "";
    retval = g_utf8_collate (da, db);
    if (retval != 0)
        return retval;

    /* the reconciled flag ... */
    if (sa->reconciled < sb->reconciled) return -1;
    if (sa->reconciled > sb->reconciled) return +1;

    /* compare amounts */
    comp = gnc_numeric_compare(xaccSplitGetAmount(sa), xaccSplitGetAmount (sb));
    if (comp < 0) return -1;
    if (comp > 0) return +1;

    comp = gnc_numeric_compare(xaccSplitGetValue(sa), xaccSplitGetValue (sb));
    if (comp < 0) return -1;
    if (comp > 0) return +1;

    /* if dates differ, return */
    if (sa->date_reconciled < sb->date_reconciled)
        return -1;
    else if (sa->date_reconciled > sb->date_reconciled)
        return 1;

    /* else, sort on guid - keeps sort stable. */
    retval = qof_instance_guid_compare(sa, sb);
    if (retval) return retval;

    return 0;
}

xaccSplitRemovePeerSplit()

void xaccSplitRemovePeerSplit	(	Split *	split,
		const Split *	other_split
	)

Remove a peer split from this split's lot-split list.

Parameters

other_split

The split whose guid to remove

Definition at line 2074 of file Split.cpp.

{
    const GncGUID* guid;

    g_return_if_fail (split != nullptr);
    g_return_if_fail (other_split != nullptr);

    guid = qof_instance_get_guid (QOF_INSTANCE (other_split));
    xaccTransBeginEdit (split->parent);
    qof_instance_kvp_remove_guid (QOF_INSTANCE (split), "lot-split",
                                  "peer_guid", guid);
    mark_split (split);
    qof_instance_set_dirty (QOF_INSTANCE (split));
    xaccTransCommitEdit (split->parent);
}

xaccSplitSetAction()

void xaccSplitSetAction	(	Split *	split,
		const char *	action
	)

The Action is an arbitrary user-assigned string.

The action field is an arbitrary user-assigned value. It is meant to be a very short (one to ten character) string that signifies the "type" of this split, such as e.g. Buy, Sell, Div, Withdraw, Deposit, ATM, Check, etc. The idea is that this field can be used to create custom reports or graphs of data. Note that the business features auto-fill this value, but doesn't depend on it. Rather than use this function directly, see 'gnc_set_num_action' in engine/engine-helpers.c & .h which takes a user-set book option for selecting the source for the num-cell (the transaction-number or the split-action field) in registers/reports into account automatically

Definition at line 1751 of file Split.cpp.

{
    if (!split || !actn) return;
    xaccTransBeginEdit (split->parent);

    CACHE_REPLACE(split->action, actn);
    qof_instance_set_dirty(QOF_INSTANCE(split));
    xaccTransCommitEdit(split->parent);

}

xaccSplitSetAmount()

void xaccSplitSetAmount	(	Split *	split,
		gnc_numeric	amount
	)

The xaccSplitSetAmount() method sets the amount in the account's commodity that the split should have.

The following four setter functions set the prices and amounts. All of the routines always maintain balance: that is, invoking any of them will cause other splits in the transaction to be modified so that the net value of the transaction is zero.

IMPORTANT: The split should be parented by an account before any of these routines are invoked! This is because the actual setting of amounts/values requires SCU settings from the account. If these are not available, then amounts/values will be set to -1/0, which is an invalid value. I believe this order dependency is a bug, but I'm too lazy to find, fix & test at the moment ...

Note

If you use this on a newly created transaction, make sure that the 'value' is also set so that it doesn't remain zero.

Definition at line 77 of file gmock-Split.cpp.

{
    ASSERT_TRUE(GNC_IS_MOCKSPLIT(split));
    gnc_mocksplit(split)->set_amount(amt);
}

xaccSplitSetBaseValue()

void xaccSplitSetBaseValue	(	Split *	split,
		gnc_numeric	value,
		const gnc_commodity *	base_currency
	)

Depending on the base_currency, set either the value or the amount of this split or both: If the base_currency is the transaction's commodity, set the value.

If it is the account's commodity, set the amount. If both, set both.

Note

WATCH OUT: When using this function and the transaction's and account's commodities are different, the amount or the value will be left as zero. This might screw up the multi-currency handling code in the register. So please think twice whether you need this function – using xaccSplitSetValue() together with xaccSplitSetAmount() is definitely the better and safer solution!

Definition at line 1320 of file Split.cpp.

{
    const gnc_commodity *currency;
    const gnc_commodity *commodity;

    if (!s) return;
    xaccTransBeginEdit (s->parent);

    if (!s->acc)
    {
        PERR ("split must have a parent account");
        return;
    }

    currency = xaccTransGetCurrency (s->parent);
    commodity = xaccAccountGetCommodity (s->acc);

    /* If the base_currency is the transaction's commodity ('currency'),
     * set the value.  If it's the account commodity, set the
     * amount. If both, set both. */
    if (gnc_commodity_equiv(currency, base_currency))
    {
        if (gnc_commodity_equiv(commodity, base_currency))
        {
            s->amount = gnc_numeric_convert(value,
                                            get_commodity_denom(s),
                                            GNC_HOW_RND_ROUND_HALF_UP);
        }
        s->value = gnc_numeric_convert(value,
                                       get_currency_denom(s),
                                       GNC_HOW_RND_ROUND_HALF_UP);
    }
    else if (gnc_commodity_equiv(commodity, base_currency))
    {
        s->amount = gnc_numeric_convert(value, get_commodity_denom(s),
                                        GNC_HOW_RND_ROUND_HALF_UP);
    }
    else
    {
        PERR ("inappropriate base currency %s "
              "given split currency=%s and commodity=%s\n",
              gnc_commodity_get_printname(base_currency),
              gnc_commodity_get_printname(currency),
              gnc_commodity_get_printname(commodity));
        return;
    }

    SET_GAINS_A_VDIRTY(s);
    mark_split (s);
    qof_instance_set_dirty(QOF_INSTANCE(s));
    xaccTransCommitEdit(s->parent);
}

xaccSplitSetDateReconciledSecs()

void xaccSplitSetDateReconciledSecs	(	Split *	split,
		time64	time
	)

Set the date on which this split was reconciled by specifying the time as time64.

Definition at line 144 of file gmock-Split.cpp.

{
    ASSERT_TRUE(GNC_IS_MOCKSPLIT(split));
    gnc_mocksplit(split)->set_date_reconciled_secs(secs);
}

xaccSplitSetMemo()

void xaccSplitSetMemo	(	Split *	split,
		const char *	memo
	)

The memo is an arbitrary string associated with a split.

It is intended to hold a short (zero to forty character) string that is displayed by the GUI along with this split. Users typically type in free form text from the GUI.

Definition at line 107 of file gmock-Split.cpp.

{
    ASSERT_TRUE(GNC_IS_MOCKSPLIT(split));
    gnc_mocksplit(split)->set_memo(memo);
}

xaccSplitSetOnlineID()

void xaccSplitSetOnlineID	(	Split *	split,
		const char *	id
	)

The online_id is the OFX/HBCI "FITID" recorded on a split when it is imported.

It is used to recognise the split on re-import so that overlapping or re-downloaded statements don't create duplicates. This is the same value (engine KVP slot "online_id") that the desktop OFX/HBCI importer reads and writes.

The setter only changes engine data: call it inside the parent transaction's edit (xaccTransBeginEdit()/xaccTransCommitEdit()), and a session save persists it. Passing NULL or "" clears the online_id.

Definition at line 122 of file gmock-Split.cpp.

{
    ASSERT_TRUE(GNC_IS_MOCKSPLIT(split));
    gnc_mocksplit(split)->set_online_id(id);
}

xaccSplitSetReconcile()

void xaccSplitSetReconcile	(	Split *	split,
		char	reconciled_flag
	)

Set the reconcile flag.

The Reconcile flag is a single char, whose values are typically are 'n', 'y', 'c'. In Transaction.h, macros are defined for typical values (e.g. CREC, YREC).

Definition at line 137 of file gmock-Split.cpp.

{
    ASSERT_TRUE(GNC_IS_MOCKSPLIT(split));
    gnc_mocksplit(split)->set_reconcile(recn);
}

xaccSplitSetSharePrice()

void xaccSplitSetSharePrice	(	Split *	split,
		gnc_numeric	price
	)

Deprecated:

The xaccSplitSetSharePrice() method sets the price of the split.

DEPRECATED - set the value and amount instead.

Definition at line 1186 of file Split.cpp.

{
    if (!s) return;

    if (gnc_numeric_zero_p (price))
        return;

    ENTER (" ");
    xaccTransBeginEdit (s->parent);

    s->value = gnc_numeric_mul(xaccSplitGetAmount(s),
                               price, get_currency_denom(s),
                               GNC_HOW_RND_ROUND_HALF_UP);

    SET_GAINS_VDIRTY(s);
    mark_split (s);
    qof_instance_set_dirty(QOF_INSTANCE(s));
    xaccTransCommitEdit(s->parent);
    LEAVE ("");
}

xaccSplitSetSharePriceAndAmount()

void xaccSplitSetSharePriceAndAmount	(	Split *	split,
		gnc_numeric	price,
		gnc_numeric	amount
	)

The xaccSplitSetSharePriceAndAmount() method will simultaneously update the share price and the number of shares.

This is a utility routine that is equivalent to a xaccSplitSetSharePrice() followed by and xaccSplitSetAmount(), except that it incurs the processing overhead of balancing only once, instead of twice.

Definition at line 1158 of file Split.cpp.

{
    if (!s) return;
    ENTER (" ");
    xaccTransBeginEdit (s->parent);

    s->amount = gnc_numeric_convert(amt, get_commodity_denom(s),
                                    GNC_HOW_RND_ROUND_HALF_UP);
    s->value  = gnc_numeric_mul(s->amount, price,
                                get_currency_denom(s), GNC_HOW_RND_ROUND_HALF_UP);

    SET_GAINS_A_VDIRTY(s);
    mark_split (s);
    qof_instance_set_dirty(QOF_INSTANCE(s));
    xaccTransCommitEdit(s->parent);
    LEAVE ("");
}

xaccSplitSetValue()

void xaccSplitSetValue	(	Split *	split,
		gnc_numeric	value
	)

The xaccSplitSetValue() method sets the value of this split in the transaction's commodity.

Note

If you use this on a newly created transaction, make sure that the 'amount' is also set so that it doesn't remain zero.

Definition at line 92 of file gmock-Split.cpp.

{
    ASSERT_TRUE(GNC_IS_MOCKSPLIT(split));
    gnc_mocksplit(split)->set_value(val);
}

xaccSplitVoidFormerAmount()

gnc_numeric xaccSplitVoidFormerAmount

(

const Split *

split

)

Returns the original pre-void amount of a split.

Parameters

split

The split in question.

Returns

A gnc_numeric containing the original value of this split. Returns a gnc_numeric of zero upon error.

Definition at line 2144 of file Split.cpp.

{
    g_return_val_if_fail(split, gnc_numeric_zero());
    auto num{qof_instance_get_path_kvp<gnc_numeric> (QOF_INSTANCE(split), {void_former_amt_str})};
    return num ? *num : gnc_numeric_zero();
}

xaccSplitVoidFormerValue()

gnc_numeric xaccSplitVoidFormerValue

(

const Split *

split

)

Returns the original pre-void value of a split.

Parameters

split

The split in question.

Returns

A gnc_numeric containing the original amount of this split. Returns a gnc_numeric of zero upon error.

Definition at line 2152 of file Split.cpp.

{
    g_return_val_if_fail(split, gnc_numeric_zero());
    auto num{qof_instance_get_path_kvp<gnc_numeric> (QOF_INSTANCE(split), {void_former_val_str})};
    return num ? *num : gnc_numeric_zero();
}

xaccTransBeginEdit()

void xaccTransBeginEdit

(

Transaction *

trans

)

The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of its component splits.

If this is not done, errors will result.

Definition at line 35 of file gmock-Transaction.cpp.

{
    ASSERT_TRUE(GNC_IS_MOCKTRANSACTION(trans));
    gnc_mocktransaction(trans)->begin_edit();
}

xaccTransClearSplits()

void xaccTransClearSplits

(

Transaction *

trans

)

Remove all splits from the transaction.

Clears the split list of the transaction. All splits that the transaction still owns will be destroyed, and others will be unlinked.

Opens and commits an edit on the transaction, so this will destroy the transaction if it isn't already open, as will committing the outer edits if new splits are not added before hand.

Definition at line 2074 of file Transaction.cpp.

{
    xaccTransBeginEdit(trans);
    /* We only own the splits that still think they belong to us.   This is done
       in 2 steps.  In the first, the splits are marked as being destroyed, but they
       are not destroyed yet.  In the second, the destruction is committed which will
       do the actual destruction.  If both steps are done for a split before they are
       done for the next split, then a split will still be on the split list after it
       has been freed.  This can cause other parts of the code (e.g. in xaccSplitDestroy())
       to reference the split after it has been freed. */
    for (auto node = trans->splits; node; node = node->next)
    {
        auto s = GNC_SPLIT(node->data);
        if (s && s->parent == trans)
        {
            xaccSplitDestroy(s);
        }
    }
    for (auto node = trans->splits; node; node = node->next)
    {
        auto s = GNC_SPLIT(node->data);
        if (s && s->parent == trans)
        {
            xaccSplitCommitEdit(s);
        }
    }
    g_list_free (trans->splits);
    trans->splits = nullptr;

    xaccTransCommitEdit(trans);
}

xaccTransCommitEdit()

void xaccTransCommitEdit

(

Transaction *

trans

)

The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are complete and should be made permanent.

Note this routine may result in the deletion of the transaction, if the transaction is "empty" (has no splits), or of xaccTransDestroy() was called on the transaction.

Definition at line 42 of file gmock-Transaction.cpp.

{
    ASSERT_TRUE(GNC_IS_MOCKTRANSACTION(trans));
    gnc_mocktransaction(trans)->commit_edit();
}

xaccTransCopyFromClipBoard()

void xaccTransCopyFromClipBoard	(	const Transaction *	from_trans,
		Transaction *	to_trans,
		const Account *	from_acc,
		Account *	to_acc,
		gboolean	no_date
	)

This function explicitly must robustly handle some unusual input.

'from_trans' may be a duped trans (see xaccDupeTransaction), so its splits may not really belong to the accounts that they say they do.

'from_acc' need not be a valid account. It may be an already freed Account. Therefore, it must not be dereferenced at all.

Neither 'from_trans', nor 'from_acc', nor any of 'from's splits may be modified in any way.

'no_date' if TRUE will not copy the date posted.

The 'to_trans' transaction will end up with valid copies of from's splits. In addition, the copies of any of from's splits that were in from_acc (or at least claimed to be) will end up in to_acc.

Definition at line 719 of file Transaction.cpp.

{
    gboolean change_accounts = FALSE;
    GList *node;

    if (!from_trans || !to_trans)
        return;

    change_accounts = from_acc && GNC_IS_ACCOUNT(to_acc) && from_acc != to_acc;
    xaccTransBeginEdit(to_trans);

    xaccTransClearSplits(to_trans);
    xaccTransSetCurrency(to_trans, xaccTransGetCurrency(from_trans));
    xaccTransSetDescription(to_trans, xaccTransGetDescription(from_trans));

    if ((xaccTransGetNum(to_trans) == nullptr) || (g_strcmp0 (xaccTransGetNum(to_trans), "") == 0))
        xaccTransSetNum(to_trans, xaccTransGetNum(from_trans));

    xaccTransSetNotes(to_trans, xaccTransGetNotes(from_trans));
    xaccTransSetDocLink(to_trans, xaccTransGetDocLink (from_trans));
    if(!no_date)
    {
        xaccTransSetDatePostedSecs(to_trans, xaccTransRetDatePosted (from_trans));
    }

    /* Each new split will be parented to 'to' */
    for (node = from_trans->splits; node; node = node->next)
    {
        Split *new_split = xaccMallocSplit( qof_instance_get_book(QOF_INSTANCE(from_trans)));
        xaccSplitCopyOnto(GNC_SPLIT(node->data), new_split);
        if (change_accounts && xaccSplitGetAccount(GNC_SPLIT(node->data)) == from_acc)
            xaccSplitSetAccount(new_split, to_acc);
        xaccSplitSetParent(new_split, to_trans);
    }
    xaccTransCommitEdit(to_trans);
}

xaccTransCopyToClipBoard()

Transaction* xaccTransCopyToClipBoard

(

const Transaction *

from_trans

)

Copy a transaction to the 'clipboard' transaction using dupe_transaction.

The 'clipboard' transaction must never be dereferenced.

Definition at line 679 of file Transaction.cpp.

{
    Transaction *to_trans;

    if (!from_trans)
        return nullptr;

    to_trans = dupe_trans(from_trans);
    return to_trans;
}

xaccTransCountSplits()

int xaccTransCountSplits

(

const Transaction *

trans

)

Returns the number of splits in this transaction.

Definition at line 2210 of file Transaction.cpp.

{
    gint i = 0;
    g_return_val_if_fail (trans != nullptr, 0);
    FOR_EACH_SPLIT(trans, i++);
    return i;
}

xaccTransDestroy()

void xaccTransDestroy

(

Transaction *

trans

)

Destroys a transaction.

Each split in transaction trans is removed from its account and destroyed as well.

If the transaction has not already been opened for editing with xaccTransBeginEdit() then the changes are committed immediately. Otherwise, the caller must follow up with either xaccTransCommitEdit(), in which case the transaction and split memory will be freed, or xaccTransRollbackEdit(), in which case nothing at all is freed, and everything is put back into original order.

Parameters

trans

the transaction to destroy

Definition at line 150 of file gmock-Transaction.cpp.

{
    ASSERT_TRUE(GNC_IS_MOCKTRANSACTION(trans));
    gnc_mocktransaction(trans)->destroy();
}

xaccTransEqual()

gboolean xaccTransEqual	(	const Transaction *	ta,
		const Transaction *	tb,
		gboolean	check_guids,
		gboolean	check_splits,
		gboolean	check_balances,
		gboolean	assume_ordered
	)

Equality.

Parameters

ta	First transaction to compare
tb	Second transaction to compare
check_guids	If TRUE, try a guid_equal() on the GUIDs of both transactions if their pointers are not equal in the first place. Also passed to subsidiary calls to xaccSplitEqual.
check_splits	If TRUE, after checking the transaction data structures for equality, also check all splits attached to the transaction for equality.
check_balances	If TRUE, when checking splits also compare balances between the two splits. Balances are recalculated whenever a split is added or removed from an account, so YMMV on whether this should be set.
assume_ordered	If TRUE, assume that the splits in each transaction appear in the same order. This saves some time looking up splits by GncGUID, and is required for checking duplicated transactions because all the splits have new GUIDs.

Definition at line 824 of file Transaction.cpp.

{
    gboolean same_book;

    if (!ta && !tb) return TRUE; /* Arguable.  FALSE may be better. */

    if (!ta || !tb)
    {
        PINFO ("one is nullptr");
        return FALSE;
    }

    if (ta == tb) return TRUE;

    same_book = qof_instance_get_book(QOF_INSTANCE(ta)) == qof_instance_get_book(QOF_INSTANCE(tb));

    if (check_guids)
    {
        if (qof_instance_guid_compare(ta, tb) != 0)
        {
            PINFO ("GUIDs differ");
            return FALSE;
        }
    }

    if (!gnc_commodity_equal(ta->common_currency, tb->common_currency))
    {
        PINFO ("commodities differ %s vs %s",
               gnc_commodity_get_unique_name (ta->common_currency),
               gnc_commodity_get_unique_name (tb->common_currency));
        return FALSE;
    }

    if (ta->date_entered != tb->date_entered)
    {
        char buf1[100];
        char buf2[100];

        (void)gnc_time64_to_iso8601_buff(ta->date_entered, buf1);
        (void)gnc_time64_to_iso8601_buff(tb->date_entered, buf2);
        PINFO ("date entered differs: '%s' vs '%s'", buf1, buf2);
        return FALSE;
    }

    if (ta->date_posted != tb->date_posted)
    {
        char buf1[100];
        char buf2[100];

        (void)gnc_time64_to_iso8601_buff(ta->date_posted, buf1);
        (void)gnc_time64_to_iso8601_buff(tb->date_posted, buf2);
        PINFO ("date posted differs: '%s' vs '%s'", buf1, buf2);
        return FALSE;
    }

    /* If the same book, since we use cached strings, we can just compare pointer
     * equality for num and description
     */
    if ((same_book && ta->num != tb->num) || (!same_book && g_strcmp0(ta->num, tb->num) != 0))
    {
        PINFO ("num differs: %s vs %s", ta->num, tb->num);
        return FALSE;
    }

    if ((same_book && ta->description != tb->description)
            || (!same_book && g_strcmp0(ta->description, tb->description)))
    {
        PINFO ("descriptions differ: %s vs %s", ta->description, tb->description);
        return FALSE;
    }

    if (qof_instance_compare_kvp (QOF_INSTANCE (ta), QOF_INSTANCE (tb)) != 0)
    {
        char *frame_a;
        char *frame_b;

        frame_a = qof_instance_kvp_as_string (QOF_INSTANCE (ta));
        frame_b = qof_instance_kvp_as_string (QOF_INSTANCE (tb));


        PINFO ("kvp frames differ:\n%s\n\nvs\n\n%s", frame_a, frame_b);

        g_free (frame_a);
        g_free (frame_b);

        return FALSE;
    }

    if (check_splits)
    {
        if ((!ta->splits && tb->splits) || (!tb->splits && ta->splits))
        {
            PINFO ("only one has splits");
            return FALSE;
        }

        if (ta->splits && tb->splits)
        {
            GList *node_a, *node_b;

            for (node_a = ta->splits, node_b = tb->splits;
                    node_a;
                    node_a = node_a->next, node_b = node_b->next)
            {
                Split *split_a = GNC_SPLIT(node_a->data);
                Split *split_b;

                /* don't presume that the splits are in the same order */
                if (!assume_ordered)
                    node_b = g_list_find_custom (tb->splits, split_a,
                                                 compare_split_guids);

                if (!node_b)
                {
                    gchar guidstr[GUID_ENCODING_LENGTH+1];
                    guid_to_string_buff (xaccSplitGetGUID (split_a),guidstr);

                    PINFO ("first has split %s and second does not",guidstr);
                    return FALSE;
                }

                split_b = GNC_SPLIT(node_b->data);

                if (!xaccSplitEqual (split_a, split_b, check_guids, check_balances,
                                     FALSE))
                {
                    char str_a[GUID_ENCODING_LENGTH + 1];
                    char str_b[GUID_ENCODING_LENGTH + 1];

                    guid_to_string_buff (xaccSplitGetGUID (split_a), str_a);
                    guid_to_string_buff (xaccSplitGetGUID (split_b), str_b);

                    PINFO ("splits %s and %s differ", str_a, str_b);
                    return FALSE;
                }
            }

            if (g_list_length (ta->splits) != g_list_length (tb->splits))
            {
                PINFO ("different number of splits");
                return FALSE;
            }
        }
    }

    return TRUE;
}

xaccTransGetAccountAmount()

gnc_numeric xaccTransGetAccountAmount	(	const Transaction *	trans,
		const Account *	account
	)

Same as xaccTransGetAccountValue, but uses the Account's commodity.

Definition at line 1154 of file Transaction.cpp.

{
    gnc_numeric total = gnc_numeric_zero ();
    if (!trans || !acc) return total;

    total = gnc_numeric_convert (total, xaccAccountGetCommoditySCU (acc),
                                 GNC_HOW_RND_ROUND_HALF_UP);
    FOR_EACH_SPLIT(trans, if (acc == xaccSplitGetAccount(s))
                   total = gnc_numeric_add_fixed(
                               total, xaccSplitGetAmount(s)));
    return total;
}

xaccTransGetAccountBalance()

gnc_numeric xaccTransGetAccountBalance	(	const Transaction *	trans,
		const Account *	account
	)

Get the account balance for the specified account after the last split in the specified transaction.

Definition at line 1228 of file Transaction.cpp.

{
    GList *node;
    Split *last_split = nullptr;

    // Not really the appropriate error value.
    g_return_val_if_fail(account && trans, gnc_numeric_error(GNC_ERROR_ARG));

    for (node = trans->splits; node; node = node->next)
    {
        Split *split = GNC_SPLIT(node->data);

        if (!xaccTransStillHasSplit(trans, split))
            continue;
        if (xaccSplitGetAccount(split) != account)
            continue;

        if (!last_split)
        {
            last_split = split;
            continue;
        }

        /* This test needs to correspond to the comparison function used when
           sorting the splits for computing the running balance. */
        if (xaccSplitOrder (last_split, split) < 0)
            last_split = split;
    }

    return xaccSplitGetBalance (last_split);
}

xaccTransGetAccountValue()

gnc_numeric xaccTransGetAccountValue	(	const Transaction *	trans,
		const Account *	account
	)

The xaccTransGetAccountValue() method returns the total value applied to a particular account.

In some cases there may be multiple Splits in a single Transaction applied to one account (in particular when trying to balance Lots) – this function is just a convenience to view everything at once.

Definition at line 1138 of file Transaction.cpp.

{
    gnc_numeric total = gnc_numeric_zero ();
    if (!trans || !acc) return total;

    FOR_EACH_SPLIT(trans, if (acc == xaccSplitGetAccount(s))
{
    total = gnc_numeric_add (total, xaccSplitGetValue (s),
                             GNC_DENOM_AUTO,
                             GNC_HOW_DENOM_EXACT);
    });
    return total;
}

xaccTransGetAPARAcctSplitList()

SplitList* xaccTransGetAPARAcctSplitList	(	const Transaction *	trans,
		gboolean	strict
	)

The xaccTransGetAPARSplitList() method returns a GList of the splits in a transaction that belong to an AR or AP account.

Parameters

trans	The transaction
strict	This slightly modifies the test to only consider splits in an AR or AP account and the split is part of a business lot

Returns

The list of splits. This list must be freed when you are done with it.

Definition at line 2147 of file Transaction.cpp.

{
    GList *apar_splits = nullptr;
    if (!trans) return nullptr;

    FOR_EACH_SPLIT (trans,
                    const Account *account = xaccSplitGetAccount(s);
                    if (account && xaccAccountIsAPARType(xaccAccountGetType(account)))
                    {

                        if (!strict)
                            apar_splits = g_list_prepend (apar_splits, s);
                        else
                        {
                            GncOwner owner;
                            GNCLot *lot = xaccSplitGetLot(s);
                            if (lot &&
                                (gncInvoiceGetInvoiceFromLot (lot) ||
                                gncOwnerGetOwnerFromLot (lot, &owner)))
                                apar_splits = g_list_prepend (apar_splits, s);
                        }
                    }
    );

    apar_splits = g_list_reverse (apar_splits);
    return apar_splits;
}

xaccTransGetCurrency()

gnc_commodity* xaccTransGetCurrency

(

const Transaction *

trans

)

Returns the valuation commodity of this transaction.

Each transaction's valuation commodity, or 'currency' is, by definition, the common currency in which all splits in the transaction can be valued. The total value of the transaction must be zero when all splits are valued in this currency.

Note

What happens if the Currency isn't set? Ans: bad things.

Definition at line 134 of file gmock-Transaction.cpp.

{
    SCOPED_TRACE("");
    auto mocktrans = gnc_mocktransaction(trans);
    return mocktrans ? mocktrans->get_currency() : nullptr;
}

xaccTransGetDate()

time64 xaccTransGetDate

(

const Transaction *

trans

)

Retrieve the posted date of the transaction.

The posted date is the date when this transaction was posted at the bank. (Although having different function names, GetDate and GetDatePosted refer to the same single date.)

Definition at line 73 of file gmock-Transaction.cpp.

{
    SCOPED_TRACE("");
    auto mocktrans = gnc_mocktransaction(trans);
    return mocktrans ? mocktrans->get_date() : 0;
}

xaccTransGetDateEntered()

time64 xaccTransGetDateEntered

(

const Transaction *

trans

)

Retrieve the date of when the transaction was entered.

The entered date is the date when the register entry was made.

Definition at line 2260 of file Transaction.cpp.

{
    return trans ? trans->date_entered : 0;
}

xaccTransGetDatePostedGDate()

GDate xaccTransGetDatePostedGDate

(

const Transaction *

trans

)

Retrieve the posted date of the transaction.

The posted date is the date when this transaction was posted at the bank.

Definition at line 2273 of file Transaction.cpp.

{
    GDate result;
    g_date_clear (&result, 1);
    if (trans)
    {
        /* Can we look up this value in the kvp slot? If yes, use it
         * from there because it doesn't suffer from time zone
         * shifts. */
        if (auto res = qof_instance_get_path_kvp<GDate> (QOF_INSTANCE(trans), {TRANS_DATE_POSTED}))
             result = *res;
        if (! g_date_valid (&result) || gdate_to_time64 (result) == INT64_MAX)
        {
             /* Well, this txn doesn't have a valid GDate saved in a slot.
              * time64_to_gdate() uses local time and we want UTC so we have
              * to write it out.
              */
             time64 time = xaccTransGetDate(trans);
             struct tm *stm = gnc_gmtime(&time);
             if (stm)
             {
                 g_date_set_dmy(&result, stm->tm_mday,
                                (GDateMonth)(stm->tm_mon + 1),
                                stm->tm_year + 1900);
                 free(stm);
             }
        }
    }
    return result;
}

xaccTransGetFirstAPARAcctSplit()

Split* xaccTransGetFirstAPARAcctSplit	(	const Transaction *	trans,
		gboolean	strict
	)

The xaccTransGetFirstPaymentAcctSplit() method returns a pointer to the first split in this transaction that belongs to an AR or AP account.

Parameters

trans	The transaction
strict	This slightly modifies the test to only consider splits in an AR or AP account and the split is part of a business lot

If there is no such split in the transaction NULL will be returned.

Definition at line 2186 of file Transaction.cpp.

{
    FOR_EACH_SPLIT (trans,
                    const Account *account = xaccSplitGetAccount(s);
                    if (account && xaccAccountIsAPARType(xaccAccountGetType(account)))
                    {
                        GNCLot *lot;
                        GncOwner owner;

                        if (!strict)
                            return s;

                        lot = xaccSplitGetLot(s);
                        if (lot &&
                            (gncInvoiceGetInvoiceFromLot (lot) ||
                            gncOwnerGetOwnerFromLot (lot, &owner)))
                            return s;
                    }
                   );

    return nullptr;
}

xaccTransGetFirstPaymentAcctSplit()

Split* xaccTransGetFirstPaymentAcctSplit

(

const Transaction *

trans

)

The xaccTransGetFirstPaymentAcctSplit() method returns a pointer to the first split in this transaction that belongs to an account which is considered a valid account for business payments.

Parameters

trans

The transaction

If there is no such split in the transaction NULL will be returned.

Definition at line 2175 of file Transaction.cpp.

{
    FOR_EACH_SPLIT (trans,
                    const Account *account = xaccSplitGetAccount(s);
                    if (account && gncBusinessIsPaymentAcctType(xaccAccountGetType(account)))
                        return s;
                   );

    return nullptr;
}

xaccTransGetImbalance()

MonetaryList* xaccTransGetImbalance

(

const Transaction *

trans

)

The xaccTransGetImbalance method returns a list giving the value of the transaction in each currency for which the balance is not zero.

If the use of currency accounts is disabled, then this will be only the common currency for the transaction and xaccTransGetImbalance becomes equivalent to xaccTransGetImbalanceValue. Otherwise it will return a list containing the imbalance in each currency.

Definition at line 1020 of file Transaction.cpp.

{
    /* imbal_value is used if either (1) the transaction has a non currency
       split or (2) all the splits are in the same currency.  If there are
       no non-currency splits and not all splits are in the same currency then
       imbal_list is used to compute the imbalance. */
    MonetaryList *imbal_list = nullptr;
    gnc_numeric imbal_value = gnc_numeric_zero();
    gboolean trading_accts;

    if (!trans) return imbal_list;

    ENTER("(trans=%p)", trans);

    trading_accts = xaccTransUseTradingAccounts (trans);

    /* If using trading accounts and there is at least one split that is not
       in the transaction currency or a split that has a price or exchange
       rate other than 1, then compute the balance in each commodity in the
       transaction.  Otherwise (all splits are in the transaction's currency)
       then compute the balance using the value fields.

       Optimize for the common case of only one currency and a balanced
       transaction. */
    FOR_EACH_SPLIT(trans,
    {
        gnc_commodity *commodity;
        commodity = xaccAccountGetCommodity(xaccSplitGetAccount(s));
        if (trading_accts &&
        (imbal_list ||
        ! gnc_commodity_equiv(commodity, trans->common_currency) ||
        ! gnc_numeric_equal(xaccSplitGetAmount(s), xaccSplitGetValue(s))))
        {
            /* Need to use (or already are using) a list of imbalances in each of
               the currencies used in the transaction. */
            if (! imbal_list)
            {
                /* All previous splits have been in the transaction's common
                   currency, so imbal_value is in this currency. */
                imbal_list = gnc_monetary_list_add_value(imbal_list,
                trans->common_currency,
                imbal_value);
            }
            imbal_list = gnc_monetary_list_add_value(imbal_list, commodity,
                         xaccSplitGetAmount(s));
        }

        /* Add it to the value accumulator in case we need it. */
        imbal_value = gnc_numeric_add(imbal_value, xaccSplitGetValue(s),
                                      GNC_DENOM_AUTO, GNC_HOW_DENOM_EXACT);
    } );


    if (!imbal_list && !gnc_numeric_zero_p(imbal_value))
    {
        /* Not balanced and no list, create one.  If we found multiple currencies
           and no non-currency commodity then imbal_list will already exist and
           we won't get here. */
        imbal_list = gnc_monetary_list_add_value(imbal_list,
                     trans->common_currency,
                     imbal_value);
    }

    /* Delete all the zero entries from the list, perhaps leaving an
       empty list */
    imbal_list = gnc_monetary_list_delete_zeros(imbal_list);

    LEAVE("(trans=%p), imbal=%p", trans, imbal_list);
    return imbal_list;
}

xaccTransGetImbalanceValue()

gnc_numeric xaccTransGetImbalanceValue

(

const Transaction *

trans

)

The xaccTransGetImbalanceValue() method returns the total value of the transaction.

In a pure double-entry system, this imbalance should be exactly zero, and if it is not, something is broken. However, when double-entry semantics are not enforced, unbalanced transactions can sneak in, and this routine can be used to find out how much things are off by. The value returned is denominated in the currency that is returned by the xaccTransFindCommonCurrency() method.

If the use of currency exchange accounts is enabled then the a a transaction must be balanced in each currency it uses to be considered to be balanced. The method xaccTransGetImbalance is used by most code to take this into consideration. This method is only used in a few places that want the transaction value even if currency exchange accounts are enabled.

Definition at line 118 of file gmock-Transaction.cpp.

{
    SCOPED_TRACE("");
    auto mocktrans = gnc_mocktransaction(trans);
    return mocktrans ? mocktrans->get_imbalance_value() : gnc_numeric_zero();
}

xaccTransGetNotes()

const char* xaccTransGetNotes

(

const Transaction *

trans

)

Gets the transaction Notes.

The Notes field is only visible in the register in double-line mode

Definition at line 103 of file gmock-Transaction.cpp.

{
    SCOPED_TRACE("");
    auto mocktrans = gnc_mocktransaction(trans);
    return mocktrans ? mocktrans->get_notes() : "";
}

xaccTransGetPaymentAcctSplitList()

SplitList* xaccTransGetPaymentAcctSplitList

(

const Transaction *

trans

)

The xaccTransGetPaymentAcctSplitList() method returns a GList of the splits in a transaction that belong to an account which is considered a valid account for business payments.

Parameters

trans

The transaction

Returns

The list of splits. This list must be freed when you are done with it.

Definition at line 2133 of file Transaction.cpp.

{
    GList *pay_splits = nullptr;
    FOR_EACH_SPLIT (trans,
                    const Account *account = xaccSplitGetAccount(s);
                    if (account && gncBusinessIsPaymentAcctType(xaccAccountGetType(account)))
                        pay_splits = g_list_prepend (pay_splits, s);
    );

    pay_splits = g_list_reverse (pay_splits);
    return pay_splits;
}

xaccTransGetReadOnly()

const char* xaccTransGetReadOnly

(

Transaction *

trans

)

Returns a non-NULL value if this Transaction was marked as read-only with some specific "reason" text.

Definition at line 2358 of file Transaction.cpp.

{
    return get_kvp_string_path (trans, {TRANS_READ_ONLY_REASON});
}

xaccTransGetReversedBy()

Transaction* xaccTransGetReversedBy

(

const Transaction *

trans

)

Returns the transaction that reversed the given transaction.

Parameters

trans

a Transaction that has been reversed

Returns

the transaction that reversed the given transaction, or NULL if the given transaction has not been reversed.

Definition at line 2626 of file Transaction.cpp.

{
    g_return_val_if_fail(trans, nullptr);
    auto g = qof_instance_get_path_kvp<GncGUID*> (QOF_INSTANCE(trans), {TRANS_REVERSED_BY});
    return g ? xaccTransLookup (*g, qof_instance_get_book (trans)) : nullptr;
}

xaccTransGetSplit()

Split* xaccTransGetSplit	(	const Transaction *	trans,
		int	i
	)

Return a pointer to the indexed split in this transaction's split list.

Note that the split list is a linked list and that indexed access is O(N). Do not use this method for iteration.

Parameters

trans	The transaction
i	The split number. Valid values for i are zero to (number_of__splits-1).

Returns

A Split* or NULL if i is out of range.

Definition at line 49 of file gmock-Transaction.cpp.

{
    SCOPED_TRACE("");
    auto mocktrans = gnc_mocktransaction(trans);
    return mocktrans ? mocktrans->get_split(i) : nullptr;
}

xaccTransGetSplitList()

SplitList* xaccTransGetSplitList

(

const Transaction *

trans

)

The xaccTransGetSplitList() method returns a GList of the splits in a transaction.

Parameters

trans

The transaction

Returns

The list of splits. This list must NOT be modified. Do NOT free this list when you are done with it.

Definition at line 57 of file gmock-Transaction.cpp.

{
    g_return_val_if_fail(GNC_IS_MOCKTRANSACTION(trans), NULL);
    return trans ? ((MockTransaction*)trans)->get_split_list() : NULL;
}

xaccTransGetTxnType()

char xaccTransGetTxnType

(

Transaction *

trans

)

Returns the Transaction Type: note this type will be derived from the transaction splits, returning TXN_TYPE_NONE, TXN_TYPE_INVOICE, TXN_TYPE_LINK, or TXN_TYPE_PAYMENT according to heuristics.

It does not query the transaction kvp slots.

See TXN_TYPE_NONE, TXN_TYPE_INVOICE and TXN_TYPE_PAYMENT

Definition at line 2319 of file Transaction.cpp.

{
    gboolean has_nonAPAR_split = FALSE;

    if (!trans) return TXN_TYPE_NONE;

    if (trans->txn_type != TXN_TYPE_UNCACHED)
        return trans->txn_type;

    trans->txn_type = TXN_TYPE_NONE;
    for (GList *n = xaccTransGetSplitList (trans); n; n = g_list_next (n))
    {
        Account *acc = xaccSplitGetAccount (GNC_SPLIT(n->data));

        if (!acc)
            continue;

        if (!xaccAccountIsAPARType (xaccAccountGetType (acc)))
            has_nonAPAR_split = TRUE;
        else if (trans->txn_type == TXN_TYPE_NONE)
        {
            GNCLot *lot = xaccSplitGetLot (GNC_SPLIT(n->data));
            GncInvoice *invoice = gncInvoiceGetInvoiceFromLot (lot);
            GncOwner owner;

            if (invoice && trans == gncInvoiceGetPostedTxn (invoice))
                trans->txn_type = TXN_TYPE_INVOICE;
            else if (invoice || gncOwnerGetOwnerFromLot (lot, &owner))
                trans->txn_type = TXN_TYPE_PAYMENT;
        }
    }

    if (!has_nonAPAR_split && (trans->txn_type == TXN_TYPE_PAYMENT))
        trans->txn_type = TXN_TYPE_LINK;

    return trans->txn_type;
}

xaccTransGetVoidReason()

const char* xaccTransGetVoidReason

(

const Transaction *

transaction

)

Returns the user supplied textual reason why a transaction was voided.

Parameters

transaction

The transaction in question.

Returns

A pointer to the user supplied reason for voiding.

Definition at line 2554 of file Transaction.cpp.

{
    return get_kvp_string_path (trans, {void_reason_str});
}

xaccTransGetVoidStatus()

gboolean xaccTransGetVoidStatus

(

const Transaction *

transaction

)

Retrieve information on whether or not a transaction has been voided.

Parameters

transaction

The transaction in question.

Returns

TRUE if the transaction is void, FALSE otherwise. Also returns FALSE upon an error.

Definition at line 2547 of file Transaction.cpp.

{
    const char *s = xaccTransGetVoidReason (trans);
    return (s && *s);
}

xaccTransGetVoidTime()

time64 xaccTransGetVoidTime

(

const Transaction *

tr

)

Returns the time that a transaction was voided.

Parameters

tr	The transaction in question.

Returns

A time64 containing the time that this transaction was voided. Returns a time of zero upon error.

Definition at line 2560 of file Transaction.cpp.

{
    auto void_str{get_kvp_string_path (tr, {void_time_str})};
    return void_str ? gnc_iso8601_to_time64_gmt (void_str) : 0;
}

xaccTransIsBalanced()

gboolean xaccTransIsBalanced

(

const Transaction *

trans

)

Returns true if the transaction is balanced according to the rules currently in effect.

Definition at line 1092 of file Transaction.cpp.

{
    MonetaryList *imbal_list;
    gboolean result;
    gnc_numeric imbal = gnc_numeric_zero();
    gnc_numeric imbal_trading = gnc_numeric_zero();

    if (trans == nullptr) return FALSE;

    if (xaccTransUseTradingAccounts(trans))
    {
        /* Transaction is imbalanced if the value is imbalanced in either
           trading or non-trading splits.  One can't be used to balance
           the other. */
        FOR_EACH_SPLIT(trans,
        {
            Account *acc = xaccSplitGetAccount(s);
            if (!acc || xaccAccountGetType(acc) != ACCT_TYPE_TRADING)
            {
                imbal = gnc_numeric_add(imbal, xaccSplitGetValue(s),
                                        GNC_DENOM_AUTO, GNC_HOW_DENOM_EXACT);
            }
            else
            {
                imbal_trading = gnc_numeric_add(imbal_trading, xaccSplitGetValue(s),
                                                GNC_DENOM_AUTO, GNC_HOW_DENOM_EXACT);
            }
        }
        );
    }
    else
        imbal = xaccTransGetImbalanceValue(trans);

    if (! gnc_numeric_zero_p(imbal) || ! gnc_numeric_zero_p(imbal_trading))
        return FALSE;

    if (!xaccTransUseTradingAccounts (trans))
        return TRUE;

    imbal_list = xaccTransGetImbalance(trans);
    result = imbal_list == nullptr;
    gnc_monetary_list_free(imbal_list);
    return result;
}

xaccTransIsOpen()

gboolean xaccTransIsOpen

(

const Transaction *

trans

)

The xaccTransIsOpen() method returns TRUE if the transaction is open for editing.

Otherwise, it returns false. XXX this routine should probably be deprecated. its, umm, hard to imagine legitimate uses (but it is used by the import/export code for reasons I can't understand.)

Definition at line 142 of file gmock-Transaction.cpp.

{
    SCOPED_TRACE("");
    auto mocktrans = gnc_mocktransaction(trans);
    return mocktrans ? mocktrans->is_open() : FALSE;
}

xaccTransIsReadonlyByPostedDate()

gboolean xaccTransIsReadonlyByPostedDate

(

const Transaction *

trans

)

Returns TRUE if this Transaction is read-only because its posted-date is older than the "auto-readonly" threshold of this book.

See qof_book_uses_autofreeze() and qof_book_get_autofreeze_gdate().

Definition at line 2386 of file Transaction.cpp.

{
    GDate *threshold_date;
    GDate trans_date;
    const QofBook *book = xaccTransGetBook (trans);
    gboolean result;
    g_assert(trans);

    if (!qof_book_uses_autoreadonly(book))
    {
        return FALSE;
    }

    if (xaccTransIsSXTemplate (trans))
    return FALSE;

    threshold_date = qof_book_get_autoreadonly_gdate(book);
    g_assert(threshold_date); // ok because we checked uses_autoreadonly before
    trans_date = xaccTransGetDatePostedGDate(trans);

//    g_warning("there is auto-read-only with days=%d, trans_date_day=%d, threshold_date_day=%d",
//              qof_book_get_num_days_autofreeze(book),
//              g_date_get_day(&trans_date),
//              g_date_get_day(threshold_date));

    if (g_date_compare(&trans_date, threshold_date) < 0)
    {
        //g_warning("we are auto-read-only");
        result = TRUE;
    }
    else
    {
        result = FALSE;
    }
    g_date_free(threshold_date);
    return result;
}

xaccTransLookup()

Transaction* xaccTransLookup	(	const GncGUID *	guid,
		QofBook *	book
	)

The xaccTransLookup() subroutine will return the transaction associated with the given id, or NULL if there is no such transaction.

Definition at line 992 of file Transaction.cpp.

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

xaccTransOrder()

int xaccTransOrder	(	const Transaction *	ta,
		const Transaction *	tb
	)

The xaccTransOrder(ta,tb) method is useful for sorting.

Orders ta and tb return <0 if ta sorts before tb return >0 if ta sorts after tb return 0 if they are absolutely equal

The comparrison uses the following fields, in order: date posted (compare as a date) num field (compare as an integer) date entered (compare as a date) description field (comcpare as a string using strcmp()) GncGUID (compare as a guid) Finally, it returns zero if all of the above match. Note that it does NOT compare its member splits. Note also that it calls xaccTransOrder_num_action with actna and actnb set as NULL.

Definition at line 1771 of file Transaction.cpp.

{
    return xaccTransOrder_num_action (ta, nullptr, tb, nullptr);
}

xaccTransOrder_num_action()

int xaccTransOrder_num_action	(	const Transaction *	ta,
		const char *	actna,
		const Transaction *	tb,
		const char *	actnb
	)

The xaccTransOrder_num_action(ta,actna,tb,actnb) method is useful for sorting.

Orders ta and tb return <0 if ta sorts before tb return >0 if ta sorts after tb return 0 if they are absolutely equal

The comparrison uses the following fields, in order: date posted (compare as a date) if actna and actnb are NULL, num field (compare as an integer) else actna and actnb (compare as an integer) date entered (compare as a date) description field (comcpare as a string using strcmp()) GncGUID (compare as a guid) Finally, it returns zero if all of the above match. Note that it does NOT compare its member splits (except action as specified above).

Definition at line 1807 of file Transaction.cpp.

{
    const char *da, *db;
    int retval;

    if (ta == tb) return 0;
    if (!tb) return -1;
    if (!ta) return +1;

    if (ta->date_posted != tb->date_posted)
        return (ta->date_posted > tb->date_posted) - (ta->date_posted < tb->date_posted);

    /* Always sort closing transactions after normal transactions */
    {
        gboolean ta_is_closing = xaccTransGetIsClosingTxn (ta);
        gboolean tb_is_closing = xaccTransGetIsClosingTxn (tb);
        if (ta_is_closing != tb_is_closing)
            return (ta_is_closing - tb_is_closing);
    }

    /* otherwise, sort on number string */
    if (actna && actnb) /* split action string, if not nullptr */
    {
         retval = order_by_int64_or_string (actna, actnb);
    }
    else                /* else transaction num string */
    {
         retval = order_by_int64_or_string (ta->num, tb->num);
    }
    if (retval)
         return retval;

    if (ta->date_entered != tb->date_entered)
        return (ta->date_entered > tb->date_entered) - (ta->date_entered < tb->date_entered);

    /* otherwise, sort on description string */
    da = ta->description ? ta->description : "";
    db = tb->description ? tb->description : "";
    retval = g_utf8_collate (da, db);
    if (retval)
        return retval;

    /* else, sort on guid - keeps sort stable. */
    return qof_instance_guid_compare(ta, tb);
}

xaccTransRecordPrice()

void xaccTransRecordPrice	(	Transaction *	trans,
		PriceSource	source
	)

The xaccTransRecordPrice() method iterates through the splits and and record the non-currency equivalent prices in the price database.

Parameters

trans	The transaction whose price is recorded
source	The price priority level

Definition at line 157 of file gmock-Transaction.cpp.

{
    g_return_if_fail(GNC_IS_MOCKTRANSACTION(trans));
    ((MockTransaction*)trans)->recordPrice();
}

xaccTransRetDateEntered()

time64 xaccTransRetDateEntered

(

const Transaction *

trans

)

Retrieve the date of when the transaction was entered.

The entered date is the date when the register entry was made.

Definition at line 2305 of file Transaction.cpp.

{
    return trans ? trans->date_entered : 0;
}

xaccTransRetDatePosted()

time64 xaccTransRetDatePosted

(

const Transaction *

trans

)

Retrieve the posted date of the transaction.

The posted date is the date when this transaction was posted at the bank. (Although having different function names, GetDate and GetDatePosted refer to the same single date.)

Definition at line 2267 of file Transaction.cpp.

{
    return trans ? trans->date_posted : 0;
}

xaccTransReverse()

Transaction* xaccTransReverse

(

Transaction *

transaction

)

xaccTransReverse creates a Transaction that reverses the given transaction by inverting all the numerical values in the given transaction.

This function cancels out the effect of an earlier transaction. This will be needed by write only accounts as a way to void a previous transaction (since you can't alter the existing transaction).

Parameters

transaction

The transaction to create a reverse of.

Returns

a new transaction which reverses the given transaction

Definition at line 2589 of file Transaction.cpp.

{
    Transaction *trans;
    g_return_val_if_fail(orig, nullptr);

    /* First edit, dirty, and commit orig to ensure that any trading
     * splits are correctly balanced.
     */
    xaccTransBeginEdit (orig);
    qof_instance_set_dirty (QOF_INSTANCE (orig));
    xaccTransCommitEdit (orig);

    trans = xaccTransClone(orig);
    g_return_val_if_fail (trans, nullptr);
    xaccTransBeginEdit(trans);

    /* Reverse the values on each split. Clear per-split info. */
    FOR_EACH_SPLIT(trans,
    {
        xaccSplitSetAmount(s, gnc_numeric_neg(xaccSplitGetAmount(s)));
        xaccSplitSetValue(s, gnc_numeric_neg(xaccSplitGetValue(s)));
        xaccSplitSetReconcile(s, NREC);
    });

    /* Now update the original with a pointer to the new one */
    qof_instance_set_path_kvp<GncGUID*> (QOF_INSTANCE (orig), guid_copy(xaccTransGetGUID(trans)),
                                         {TRANS_REVERSED_BY});

    /* Make sure the reverse transaction is not read-only */
    xaccTransClearReadOnly(trans);

    qof_instance_set_dirty(QOF_INSTANCE(trans));
    xaccTransCommitEdit(trans);
    return trans;
}

xaccTransRollbackEdit()

void xaccTransRollbackEdit

(

Transaction *

trans

)

The xaccTransRollbackEdit() routine rejects all edits made, and sets the transaction back to where it was before the editing started.

This includes restoring any deleted splits, removing any added splits, and undoing the effects of xaccTransDestroy, as well as restoring share quantities, memos, descriptions, etc.

Todo:

Fix transrollbackedit in QOF so that rollback is exposed via the API.

Definition at line 1604 of file Transaction.cpp.

{
    GList *node, *onode;
    QofBackend *be;
    Transaction *orig;
    GList *slist;
    int num_preexist, i;

/* FIXME: This isn't quite the right way to handle nested edits --
 * there should be a stack of transaction states that are popped off
 * and restored at each level -- but it does prevent restoring to the
 * editlevel 0 state until one is returning to editlevel 0, and
 * thereby prevents a crash caused by trans->orig getting nullptred too
 * soon.
 */
    if (!qof_instance_get_editlevel (QOF_INSTANCE (trans))) return;
    if (qof_instance_get_editlevel (QOF_INSTANCE (trans)) > 1) {
     qof_instance_decrease_editlevel (QOF_INSTANCE (trans));
     return;
    }

    ENTER ("trans addr=%p\n", trans);

    check_open(trans);

    /* copy the original values back in. */

    orig = trans->orig;
    std::swap (trans->num, orig->num);
    std::swap (trans->description, orig->description);
    trans->date_entered = orig->date_entered;
    trans->date_posted = orig->date_posted;
    std::swap (trans->common_currency, orig->common_currency);
    qof_instance_swap_kvp (QOF_INSTANCE (trans), QOF_INSTANCE (orig));

    /* The splits at the front of trans->splits are exactly the same
       splits as in the original, but some of them may have changed, so
       we restore only those. */
/* FIXME: Runs off the transaction's splits, so deleted splits are not
 * restored!
 */
    num_preexist = g_list_length(orig->splits);
    slist = g_list_copy(trans->splits);
    for (i = 0, node = slist, onode = orig->splits; node;
            i++, node = node->next, onode = onode ? onode->next : nullptr)
    {
        Split *s = GNC_SPLIT(node->data);

        if (!qof_instance_is_dirty(QOF_INSTANCE(s)))
            continue;

        if (i < num_preexist && onode)
        {
            Split *so = GNC_SPLIT(onode->data);

            xaccSplitRollbackEdit(s);
            std::swap (s->action, so->action);
            std::swap (s->memo, so->memo);
            qof_instance_copy_kvp (QOF_INSTANCE (s), QOF_INSTANCE (so));
            s->reconciled = so->reconciled;
            s->amount = so->amount;
            s->value = so->value;
            s->lot = so->lot;
            s->gains_split = so->gains_split;
            //SET_GAINS_A_VDIRTY(s);
            s->date_reconciled = so->date_reconciled;
            qof_instance_mark_clean(QOF_INSTANCE(s));
        }
        else
        {
            /* Potentially added splits */
            if (trans != xaccSplitGetParent(s))
            {
                trans->splits = g_list_remove(trans->splits, s);
                /* New split added, but then moved to another
                   transaction */
                continue;
            }
            xaccSplitRollbackEdit(s);
            trans->splits = g_list_remove(trans->splits, s);
            g_assert(trans != xaccSplitGetParent(s));
            /* NB: our memory management policy here is that a new split
               added to the transaction which is then rolled-back still
               belongs to the engine.  Specifically, it's freed by the
               transaction to which it was added.  Don't add the Split to
               more than one transaction during the begin/commit block! */
            if (nullptr == xaccSplitGetParent(s))
            {
                xaccFreeSplit(s);  // a newly malloc'd split
            }
        }
    }
    g_list_free(slist);

    // orig->splits may still have duped splits so free them
    g_list_free_full (orig->splits, (GDestroyNotify)xaccFreeSplit);
    orig->splits = nullptr;

    /* Now that the engine copy is back to its original version,
     * get the backend to fix it in the database */
    be = qof_book_get_backend(qof_instance_get_book(trans));
    if (qof_backend_can_rollback (be))
    {
        QofBackendError errcode;

        /* clear errors */
        do
        {
            errcode = qof_backend_get_error (be);
        }
        while (ERR_BACKEND_NO_ERR != errcode);

        qof_backend_rollback_instance (be, &(trans->inst));

        errcode = qof_backend_get_error (be);
        if (ERR_BACKEND_MOD_DESTROY == errcode)
        {
            /* The backend is asking us to delete this transaction.
             * This typically happens because another (remote) user
             * has deleted this transaction, and we haven't found
             * out about it until this user tried to edit it.
             */
            xaccTransDestroy (trans);
            do_destroy (QOF_INSTANCE(trans));

            /* push error back onto the stack */
            qof_backend_set_error (be, errcode);
            LEAVE ("deleted trans addr=%p\n", trans);
            return;
        }
        if (ERR_BACKEND_NO_ERR != errcode)
        {
            PERR ("Rollback Failed.  Ouch!");
            /* push error back onto the stack */
            qof_backend_set_error (be, errcode);
        }
    }

    if (!qof_book_is_readonly(qof_instance_get_book(trans)))
        xaccTransWriteLog (trans, 'R');

    xaccFreeTransaction (trans->orig);

    trans->orig = nullptr;
    qof_instance_set_destroying(trans, FALSE);

    /* Put back to zero. */
    qof_instance_decrease_editlevel(trans);
    /* FIXME: The register code seems to depend on the engine to
       generate an event during rollback, even though the state is just
       reverting to what it was. */
    gen_event_trans (trans);

    LEAVE ("trans addr=%p\n", trans);
}

xaccTransScrubGains()

void xaccTransScrubGains	(	Transaction *	trans,
		Account *	gain_acc
	)

The xaccTransScrubGains() routine performs a number of cleanup functions on the indicated transaction, with the end-goal of setting up a consistent set of gains/losses for all the splits in the transaction.

This includes making sure that the lot assignments of all the splits are good, and that the lots balance appropriately.

Definition at line 2676 of file Transaction.cpp.

{
    SplitList *node;

    ENTER("(trans=%p)", trans);
    /* Lock down posted date, its to be synced to the posted date
     * for the source of the cap gains. */
    xaccTransScrubGainsDate(trans);

    /* Fix up the split amount */
restart:
    for (node = trans->splits; node; node = node->next)
    {
        Split *s = GNC_SPLIT(node->data);

        if (!xaccTransStillHasSplit(trans, s)) continue;

        xaccSplitDetermineGainStatus(s);
        if (s->gains & GAINS_STATUS_ADIRTY)
        {
            gboolean altered = FALSE;
            s->gains &= ~GAINS_STATUS_ADIRTY;
            if (s->lot)
                altered = xaccScrubLot(s->lot);
            else
                altered = xaccSplitAssign(s);
            if (altered) goto restart;
        }
    }

    /* Fix up gains split value */
    FOR_EACH_SPLIT(trans,
                   if ((s->gains & GAINS_STATUS_VDIRTY) ||
                       (s->gains_split &&
                        (s->gains_split->gains & GAINS_STATUS_VDIRTY)))
                       xaccSplitComputeCapGains(s, gain_acc);
        );

    LEAVE("(trans=%p)", trans);
}

xaccTransSetCurrency()

void xaccTransSetCurrency	(	Transaction *	trans,
		gnc_commodity *	curr
	)

Set the commodity of this transaction.

Set the commodity of this transaction.

When we do that to a transaction with splits we need to re-value all of the splits in the new currency.

Parameters

trans	The transaction to change
curr	The new currency to set.

Definition at line 1325 of file Transaction.cpp.

{
    gnc_commodity *old_curr = trans->common_currency;
    if (!trans || !curr || trans->common_currency == curr) return;
    xaccTransBeginEdit(trans);

    trans->common_currency = curr;
    if (old_curr != nullptr && trans->splits != nullptr)
    {
        gnc_numeric rate = find_new_rate(trans, curr);
        if (!gnc_numeric_zero_p (rate))
        {
            FOR_EACH_SPLIT(trans, split_set_new_value(s, curr, old_curr, rate));
        }
        else
        {
            FOR_EACH_SPLIT(trans, xaccSplitSetValue(s, xaccSplitGetValue(s)));
        }
    }

    qof_instance_set_dirty(QOF_INSTANCE(trans));
    mark_trans(trans);  /* Dirty balance of every account in trans */
    xaccTransCommitEdit(trans);
}

xaccTransSetDate()

void xaccTransSetDate	(	Transaction *	trans,
		int	day,
		int	mon,
		int	year
	)

The xaccTransSetDate() method does the same thing as xaccTransSetDate[Posted]Secs(), but takes a convenient day-month-year format.

(Footnote: this shouldn't matter to a user, but anyone modifying the engine should understand that when xaccTransCommitEdit() is called, the date order of each of the component splits will be checked, and will be restored in ascending date order.)

Definition at line 1950 of file Transaction.cpp.

{
    if (!trans) return;
    GDate date;
    g_date_clear (&date, 1);
    if (g_date_valid_dmy (day, static_cast<GDateMonth>(mon), year))
        g_date_set_dmy (&date, day, static_cast<GDateMonth>(mon), year);
    else
    {
        PWARN("Attempted to set invalid date %d-%d-%d; set today's date instead.",
              year, mon, day);
        gnc_gdate_set_today (&date);
    }
    xaccTransSetDatePostedGDate(trans, date);
}

xaccTransSetDateEnteredSecs()

void xaccTransSetDateEnteredSecs	(	Transaction *	trans,
		time64	time
	)

Modify the date of when the transaction was entered.

The entered date is the date when the register entry was made.

Definition at line 1943 of file Transaction.cpp.

{
    if (!trans) return;
    xaccTransSetDateInternal(trans, &trans->date_entered, secs);
}

xaccTransSetDatePostedGDate()

void xaccTransSetDatePostedGDate	(	Transaction *	trans,
		GDate	date
	)

This method modifies posted date of the transaction, specified by a GDate.

The posted date is the date when this transaction was posted at the bank.

This is identical to xaccTransSetDate(), but different from xaccTransSetDatePostedSecs which artificially introduces the time-of-day part, which needs to be ignored.

Definition at line 1927 of file Transaction.cpp.

{
    if (!trans) return;

    /* We additionally save this date into a kvp frame to ensure in
     * the future a date which was set as *date* (without time) can
     * clearly be distinguished from the time64. */
    qof_instance_set_path_kvp<GDate> (QOF_INSTANCE(trans), date, {TRANS_DATE_POSTED});
    qof_instance_set_dirty (QOF_INSTANCE(trans));
    /* mark dirty and commit handled by SetDateInternal */
    xaccTransSetDateInternal(trans, &trans->date_posted,
                             gdate_to_time64(date));
    set_gains_date_dirty (trans);
}

xaccTransSetDatePostedSecs()

void xaccTransSetDatePostedSecs	(	Transaction *	trans,
		time64	time
	)

The xaccTransSetDatePostedSecs() method will modify the posted date of the transaction, specified by a time64 (see ctime(3)).

The posted date is the date when this transaction was posted at the bank.

Please do not use this function, as the extra time-of-day part messes up a lot of places. Rather, please use xaccTransSetDatePostedGDate() or xaccTransSetDatePostedSecsNormalized().

Definition at line 1911 of file Transaction.cpp.

{
    if (!trans) return;
    xaccTransSetDateInternal(trans, &trans->date_posted, secs);
    set_gains_date_dirty(trans);
}

xaccTransSetDatePostedSecsNormalized()

void xaccTransSetDatePostedSecsNormalized	(	Transaction *	trans,
		time64	time
	)

This function sets the posted date of the transaction, specified by a time64 (see ctime(3)).

Contrary to xaccTransSetDatePostedSecs(), the time will be normalized to only the date part, and the time-of-day will be ignored. The resulting date is the same as if it had been set as a GDate through xaccTransSetDatePostedGDate().

Please prefer this function over xaccTransSetDatePostedSecs().

The posted date is the date when this transaction was posted at the bank.

Definition at line 81 of file gmock-Transaction.cpp.

{
    ASSERT_TRUE(GNC_IS_MOCKTRANSACTION(trans));
    gnc_mocktransaction(trans)->set_date_posted_secs_normalized(time);
}

xaccTransSetNotes()

void xaccTransSetNotes	(	Transaction *	trans,
		const char *	notes
	)

Sets the transaction Notes.

The Notes field is only visible in the register in double-line mode

Definition at line 111 of file gmock-Transaction.cpp.

{
    ASSERT_TRUE(GNC_IS_MOCKTRANSACTION(trans));
    gnc_mocktransaction(trans)->set_notes(notes);
}

xaccTransSetReadOnly()

void xaccTransSetReadOnly	(	Transaction *	trans,
		const char *	reason
	)

Set the transaction to be ReadOnly by setting a non-NULL value as "reason".

FIXME: If "reason" is NULL, this function does nothing, instead of removing the readonly flag; the actual removal is possible only through xaccTransClearReadOnly().

Definition at line 1989 of file Transaction.cpp.

{
    if (trans && reason)
        set_kvp_string_path (trans, {TRANS_READ_ONLY_REASON}, reason);
}

xaccTransSetTxnType()

void xaccTransSetTxnType	(	Transaction *	trans,
		char	type
	)

Set the Transaction Type: note the type will be saved into the Transaction kvp property as a backward compatibility measure, for previous GnuCash versions whose xaccTransGetTxnType reads from the kvp slots.

See TXN_TYPE_NONE, TXN_TYPE_INVOICE and TXN_TYPE_PAYMENT

Definition at line 1977 of file Transaction.cpp.

{
    char s[2] = {type, '\0'};
    set_kvp_string_path (trans, {TRANS_TXN_TYPE_KVP}, s);
}

xaccTransUnvoid()

void xaccTransUnvoid

(

Transaction *

transaction

)

xaccTransUnvoid restores a voided transaction to its original state.

At some point when gnucash is enhanced to support an audit trail (i.e. write only transactions) this command should be automatically disabled when the audit trail feature is enabled.

Parameters

transaction

The transaction to restore from voided state.

Definition at line 2567 of file Transaction.cpp.

{
    g_return_if_fail(trans);

    if (xaccTransGetVoidReason (trans) == nullptr)
        return; /* Transaction isn't voided. Bail. */

    xaccTransBeginEdit(trans);

    set_kvp_string_path (trans, {trans_notes_str}, get_kvp_string_path (trans, {void_former_notes_str}));
    set_kvp_string_path (trans, {void_former_notes_str}, nullptr);
    set_kvp_string_path (trans, {void_reason_str}, nullptr);
    set_kvp_string_path (trans, {void_time_str}, nullptr);

    FOR_EACH_SPLIT(trans, xaccSplitUnvoid(s));

    /* Dirtying taken care of by ClearReadOnly */
    xaccTransClearReadOnly(trans);
    xaccTransCommitEdit(trans);
}

xaccTransVoid()

void xaccTransVoid	(	Transaction *	transaction,
		const char *	reason
	)

xaccTransVoid voids a transaction.

A void transaction has no values, is unaffected by reconciliation, and, by default is not included in any queries. A voided transaction may not be altered.

Parameters

transaction	The transaction to void.
reason	The textual reason why this transaction is being voided.

Definition at line 2516 of file Transaction.cpp.

{
    g_return_if_fail(trans && reason);

    /* Prevent voiding transactions that are already marked
     * read only, for example generated by the business features.
     */
    if (xaccTransGetReadOnly (trans))
    {
        PWARN ("Refusing to void a read-only transaction!");
        return;
    }
    xaccTransBeginEdit(trans);

    char iso8601_str[ISO_DATELENGTH + 1] = "";
    gnc_time64_to_iso8601_buff (gnc_time(nullptr), iso8601_str);

    if (auto s = get_kvp_string_path (trans, {trans_notes_str}))
        set_kvp_string_path (trans, {void_former_notes_str}, s);
    set_kvp_string_path (trans, {trans_notes_str}, _("Voided transaction"));
    set_kvp_string_path (trans, {void_reason_str}, reason);
    set_kvp_string_path (trans, {void_time_str}, iso8601_str);

    FOR_EACH_SPLIT(trans, xaccSplitVoid(s));

    /* Dirtying taken care of by SetReadOnly */
    xaccTransSetReadOnly(trans, _("Transaction Voided"));
    xaccTransCommitEdit(trans);
}