GnuCash  5.6-38-g01bffa485a+
Files | Macros | Functions

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 xaccSplitReturnGUID(X)   (X ? *(qof_entity_get_guid(QOF_INSTANCE(X))) : *(guid_null()))
 
#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))
 
#define xaccTransReturnGUID(X)   (X ? *(qof_entity_get_guid(QOF_INSTANCE(X))) : *(guid_null()))
 

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

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...
 
AccountxaccSplitGetAccount (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 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...
 
GList * xaccSplitListGetUniqueTransactionsReversed (const GList *splits)
 
GList * xaccSplitListGetUniqueTransactions (const GList *splits)
 
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()
 
SplitListxaccTransGetSplitList (const Transaction *trans)
 The xaccTransGetSplitList() method returns a GList of the splits in a transaction. More...
 
SplitListxaccTransGetPaymentAcctSplitList (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...
 
SplitListxaccTransGetAPARAcctSplitList (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...
 
gboolean xaccTransInFutureByPostedDate (const Transaction *trans)
 Returns TRUE if this Transaction's posted-date is in the future.
 
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...
 
gboolean xaccTransGetRateForCommodity (const Transaction *trans, const gnc_commodity *split_com, const Split *split_to_exclude, gnc_numeric *rate)
 
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 555 of file Split.h.

◆ xaccSplitReturnGUID

#define xaccSplitReturnGUID (   X)    (X ? *(qof_entity_get_guid(QOF_INSTANCE(X))) : *(guid_null()))
Deprecated:

Definition at line 557 of file Split.h.

◆ xaccTransAppendSplit

#define xaccTransAppendSplit (   t,
 
)    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 381 of file Transaction.h.

◆ xaccTransGetBook

#define xaccTransGetBook (   X)    qof_instance_get_book (QOF_INSTANCE(X))
Deprecated:

Definition at line 802 of file Transaction.h.

◆ xaccTransGetGUID

#define xaccTransGetGUID (   X)    qof_entity_get_guid(QOF_INSTANCE(X))
Deprecated:

Definition at line 804 of file Transaction.h.

◆ xaccTransReturnGUID

#define xaccTransReturnGUID (   X)    (X ? *(qof_entity_get_guid(QOF_INSTANCE(X))) : *(guid_null()))
Deprecated:

Definition at line 806 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 2700 of file Transaction.cpp.

2701 {
2702  guint count = 0;
2703  xaccAccountTreeForEachTransaction(gnc_book_get_root_account(book),
2704  counter_thunk, (void*)&count);
2705  return count;
2706 }
int xaccAccountTreeForEachTransaction(Account *acc, TransactionCallback proc, void *data)
Traverse all of the transactions in the given account group.

◆ xaccMallocSplit()

Split* xaccMallocSplit ( QofBook *  book)

Constructor.

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

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

◆ 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 502 of file Transaction.cpp.

503 {
504  Transaction *trans;
505 
506  g_return_val_if_fail (book, nullptr);
507 
508  trans = GNC_TRANSACTION(g_object_new(GNC_TYPE_TRANSACTION, nullptr));
509  xaccInitTransaction (trans, book);
510  qof_event_gen (&trans->inst, QOF_EVENT_CREATE, nullptr);
511 
512  return trans;
513 }
void qof_event_gen(QofInstance *entity, QofEventId event_id, gpointer event_data)
Invoke all registered event handlers using the given arguments.
Definition: qofevent.cpp:231

◆ 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_splitThe split whose guid to add
timestampThe time to be recorded for the split.

Definition at line 2047 of file Split.cpp.

2049 {
2050  const GncGUID* guid;
2051 
2052  g_return_if_fail (split != nullptr);
2053  g_return_if_fail (other_split != nullptr);
2054 
2055  guid = qof_instance_get_guid (QOF_INSTANCE (other_split));
2056  xaccTransBeginEdit (split->parent);
2057  qof_instance_kvp_add_guid (QOF_INSTANCE (split), "lot-split",
2058  gnc_time(nullptr), "peer_guid", guid_copy(guid));
2059  mark_split (split);
2060  qof_instance_set_dirty (QOF_INSTANCE (split));
2061  xaccTransCommitEdit (split->parent);
2062 }
const GncGUID * qof_instance_get_guid(gconstpointer inst)
Return the GncGUID of this instance.
GncGUID * guid_copy(const GncGUID *guid)
Returns a newly allocated GncGUID that matches the passed-in GUID.
Definition: guid.cpp:120
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
time64 gnc_time(time64 *tbuf)
get the current time
Definition: gnc-date.cpp:261
The type used to store guids in C.
Definition: guid.h:75

◆ xaccSplitCompareAccountCodes()

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

Compare two splits by code of account.

Returns similar to strcmp.

Definition at line 1707 of file Split.cpp.

1708 {
1709  Account *aa, *ab;
1710  if (!sa && !sb) return 0;
1711  if (!sa) return -1;
1712  if (!sb) return 1;
1713 
1714  aa = sa->acc;
1715  ab = sb->acc;
1716 
1717  return g_strcmp0(xaccAccountGetCode(aa), xaccAccountGetCode(ab));
1718 }
const char * xaccAccountGetCode(const Account *acc)
Get the account's accounting code.
Definition: Account.cpp:3335

◆ xaccSplitCompareAccountFullNames()

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

Compare two splits by full name of account.

Returns similar to strcmp.

Definition at line 1686 of file Split.cpp.

1687 {
1688  Account *aa, *ab;
1689  char *full_a, *full_b;
1690  int retval;
1691  if (!sa && !sb) return 0;
1692  if (!sa) return -1;
1693  if (!sb) return 1;
1694 
1695  aa = sa->acc;
1696  ab = sb->acc;
1697  full_a = gnc_account_get_full_name(aa);
1698  full_b = gnc_account_get_full_name(ab);
1699  retval = g_utf8_collate(full_a, full_b);
1700  g_free(full_a);
1701  g_free(full_b);
1702  return retval;
1703 }
gchar * gnc_account_get_full_name(const Account *account)
The gnc_account_get_full_name routine returns the fully qualified name of the account using the given...
Definition: Account.cpp:3287

◆ 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 1742 of file Split.cpp.

1743 {
1744  const char *ca, *cb;
1745  if (!sa && !sb) return 0;
1746  if (!sa) return -1;
1747  if (!sb) return 1;
1748 
1749  ca = xaccSplitGetCorrAccountCode(sa);
1750  cb = xaccSplitGetCorrAccountCode(sb);
1751  return g_strcmp0(ca, cb);
1752 }
const char * xaccSplitGetCorrAccountCode(const Split *sa)
document me
Definition: Split.cpp:1669

◆ 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 1721 of file Split.cpp.

1722 {
1723  char *ca, *cb;
1724  int retval;
1725  if (!sa && !sb) return 0;
1726  if (!sa) return -1;
1727  if (!sb) return 1;
1728 
1729  /* doesn't matter what separator we use
1730  * as long as they are the same
1731  */
1732 
1735  retval = g_strcmp0(ca, cb);
1736  g_free(ca);
1737  g_free(cb);
1738  return retval;
1739 }
char * xaccSplitGetCorrAccountFullName(const Split *sa)
These functions take a split, get the corresponding split on the "other side" of the transaction...
Definition: Split.cpp:1653

◆ 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 638 of file Split.cpp.

639 {
640  if (!from_split || !to_split) return;
641  xaccTransBeginEdit (to_split->parent);
642 
643  xaccSplitSetMemo(to_split, xaccSplitGetMemo(from_split));
644  xaccSplitSetAction(to_split, xaccSplitGetAction(from_split));
645  xaccSplitSetAmount(to_split, xaccSplitGetAmount(from_split));
646  xaccSplitSetValue(to_split, xaccSplitGetValue(from_split));
647  /* Setting the account is okay here because, even though the from
648  split might not really belong to the account it claims to,
649  setting the account won't cause any event involving from. */
650  xaccSplitSetAccount(to_split, xaccSplitGetAccount(from_split));
651  /* N.B. Don't set parent. */
652 
653  qof_instance_set_dirty(QOF_INSTANCE(to_split));
654  xaccTransCommitEdit(to_split->parent);
655 }
void xaccSplitSetValue(Split *s, gnc_numeric amt)
The xaccSplitSetValue() method sets the value of this split in the transaction's commodity.
Definition: Split.cpp:1293
void xaccSplitSetAction(Split *split, const char *actn)
The Action is an arbitrary user-assigned string.
Definition: Split.cpp:1781
void xaccSplitSetAmount(Split *s, gnc_numeric amt)
The xaccSplitSetAmount() method sets the amount in the account's commodity that the split should have...
Definition: Split.cpp:1257
void xaccSplitSetMemo(Split *split, const char *memo)
The memo is an arbitrary string associated with a split.
Definition: Split.cpp:1762
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
gnc_numeric xaccSplitGetValue(const Split *split)
Returns the value of this split in the transaction's commodity.
Definition: Split.cpp:1955
Account * xaccSplitGetAccount(const Split *s)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: Split.cpp:968
const char * xaccSplitGetMemo(const Split *split)
Returns the memo string.
Definition: Split.cpp:1930
const char * xaccSplitGetAction(const Split *split)
Returns the action string.
Definition: Split.cpp:1936
gnc_numeric xaccSplitGetAmount(const Split *split)
Returns the amount of the split in the account's commodity.
Definition: Split.cpp:1949

◆ 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 1504 of file Split.cpp.

1505 {
1506  Account *acc;
1507  Transaction *trans;
1508  GncEventData ed;
1509 
1510  if (!split) return TRUE;
1511 
1512  acc = split->acc;
1513  trans = split->parent;
1514  if (acc && !qof_instance_get_destroying(acc)
1515  && !qof_instance_get_destroying(trans)
1516  && xaccTransGetReadOnly(trans))
1517  return FALSE;
1518 
1519  xaccTransBeginEdit(trans);
1520  ed.node = split;
1521  ed.idx = xaccTransGetSplitIndex(trans, split);
1522  qof_instance_set_dirty(QOF_INSTANCE(split));
1523  qof_instance_set_destroying(split, TRUE);
1524  qof_event_gen(&trans->inst, GNC_EVENT_ITEM_REMOVED, &ed);
1525  xaccTransCommitEdit(trans);
1526 
1527  return TRUE;
1528 }
const char * xaccTransGetReadOnly(Transaction *trans)
Returns a non-NULL value if this Transaction was marked as read-only with some specific "reason" text...
gboolean qof_instance_get_destroying(gconstpointer ptr)
Retrieve the flag that indicates whether or not this object is about to be destroyed.
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
int xaccTransGetSplitIndex(const Transaction *trans, const Split *split)
Inverse of xaccTransGetSplit()
void qof_event_gen(QofInstance *entity, QofEventId event_id, gpointer event_data)
Invoke all registered event handlers using the given arguments.
Definition: qofevent.cpp:231

◆ xaccSplitEqual()

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

Equality.

Parameters
saFirst split to compare
sbSecond split to compare
check_guidsIf TRUE, try a guid_equal() on the GUIDs of both splits if their pointers are not equal in the first place.
check_balancesIf 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_splitsIf 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 801 of file Split.cpp.

805 {
806  gboolean same_book;
807 
808  if (!sa && !sb) return TRUE; /* Arguable. FALSE is better, methinks */
809 
810  if (!sa || !sb)
811  {
812  PINFO ("one is nullptr");
813  return FALSE;
814  }
815 
816  if (sa == sb) return TRUE;
817 
818  same_book = qof_instance_get_book(QOF_INSTANCE(sa)) == qof_instance_get_book(QOF_INSTANCE(sb));
819 
820  if (check_guids)
821  {
822  if (qof_instance_guid_compare(sa, sb) != 0)
823  {
824  PINFO ("GUIDs differ");
825  return FALSE;
826  }
827  }
828 
829  /* If the same book, since these strings are cached we can just use pointer equality */
830  if ((same_book && sa->memo != sb->memo) || (!same_book && g_strcmp0(sa->memo, sb->memo) != 0))
831  {
832  PINFO ("memos differ: (%p)%s vs (%p)%s",
833  sa->memo, sa->memo, sb->memo, sb->memo);
834  return FALSE;
835  }
836 
837  if ((same_book && sa->action != sb->action) || (!same_book && g_strcmp0(sa->action, sb->action) != 0))
838  {
839  PINFO ("actions differ: %s vs %s", sa->action, sb->action);
840  return FALSE;
841  }
842 
843  if (qof_instance_compare_kvp (QOF_INSTANCE (sa), QOF_INSTANCE (sb)) != 0)
844  {
845  char *frame_a;
846  char *frame_b;
847 
848  frame_a = qof_instance_kvp_as_string (QOF_INSTANCE (sa));
849  frame_b = qof_instance_kvp_as_string (QOF_INSTANCE (sb));
850 
851  PINFO ("kvp frames differ:\n%s\n\nvs\n\n%s", frame_a, frame_b);
852 
853  g_free (frame_a);
854  g_free (frame_b);
855 
856  return FALSE;
857  }
858 
859  if (sa->reconciled != sb->reconciled)
860  {
861  PINFO ("reconcile flags differ: %c vs %c", sa->reconciled, sb->reconciled);
862  return FALSE;
863  }
864 
865  if (sa->date_reconciled != sb->date_reconciled)
866  {
867  PINFO ("reconciled date differs");
868  return FALSE;
869  }
870 
872  {
873  char *str_a;
874  char *str_b;
875 
878 
879  PINFO ("amounts differ: %s vs %s", str_a, str_b);
880 
881  g_free (str_a);
882  g_free (str_b);
883 
884  return FALSE;
885  }
886 
888  {
889  char *str_a;
890  char *str_b;
891 
894 
895  PINFO ("values differ: %s vs %s", str_a, str_b);
896 
897  g_free (str_a);
898  g_free (str_b);
899 
900  return FALSE;
901  }
902 
903  if (check_balances)
904  {
905  if (!xaccSplitEqualCheckBal ("", sa->balance, sb->balance))
906  return FALSE;
907  if (!xaccSplitEqualCheckBal ("cleared ", sa->cleared_balance,
908  sb->cleared_balance))
909  return FALSE;
910  if (!xaccSplitEqualCheckBal ("reconciled ", sa->reconciled_balance,
911  sb->reconciled_balance))
912  return FALSE;
913  if (!xaccSplitEqualCheckBal ("noclosing ", sa->noclosing_balance,
914  sb->noclosing_balance))
915  return FALSE;
916  }
917 
918  if (!xaccTransEqual(sa->parent, sb->parent, check_guids, check_txn_splits,
919  check_balances, FALSE))
920  {
921  PINFO ("transactions differ");
922  return FALSE;
923  }
924 
925  return TRUE;
926 }
QofBook * qof_instance_get_book(gconstpointer inst)
Return the book pointer.
#define PINFO(format, args...)
Print an informational note.
Definition: qoflog.h:256
gchar * gnc_numeric_to_string(gnc_numeric n)
Convert to string.
gboolean xaccTransEqual(const Transaction *ta, const Transaction *tb, gboolean check_guids, gboolean check_splits, gboolean check_balances, gboolean assume_ordered)
Equality.
gboolean gnc_numeric_eq(gnc_numeric a, gnc_numeric b)
Equivalence predicate: Returns TRUE (1) if a and b are exactly the same (have the same numerator and ...
gnc_numeric xaccSplitGetValue(const Split *split)
Returns the value of this split in the transaction's commodity.
Definition: Split.cpp:1955
gint qof_instance_guid_compare(gconstpointer ptr1, gconstpointer ptr2)
Compare the GncGUID values of two instances.
gnc_numeric xaccSplitGetAmount(const Split *split)
Returns the amount of the split in the account's commodity.
Definition: Split.cpp:1949

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

54 {
55  SCOPED_TRACE("");
56  auto mocksplit = gnc_mocksplit(split);
57  return mocksplit ? mocksplit->get_account() : nullptr;
58 }

◆ 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 136 of file gmock-Split.cpp.

137 {
138  SCOPED_TRACE("");
139  auto mocksplit = gnc_mocksplit(split);
140  return mocksplit ? mocksplit->get_action() : "";
141 }

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

70 {
71  SCOPED_TRACE("");
72  auto mocksplit = gnc_mocksplit(split);
73  return mocksplit ? mocksplit->get_amount() : gnc_numeric_zero();
74 }

◆ 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 1329 of file Split.cpp.

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

◆ 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 1408 of file Split.cpp.

1409 {
1410  if (!s || !s->acc || !s->parent) return gnc_numeric_zero();
1411 
1412  /* be more precise -- the value depends on the currency we want it
1413  * expressed in. */
1414  if (gnc_commodity_equiv(xaccTransGetCurrency(s->parent), base_currency))
1415  return xaccSplitGetValue(s);
1416  if (gnc_commodity_equiv(xaccAccountGetCommodity(s->acc), base_currency))
1417  return xaccSplitGetAmount(s);
1418 
1419  PERR ("inappropriate base currency %s "
1420  "given split currency=%s and commodity=%s\n",
1421  gnc_commodity_get_printname(base_currency),
1424  return gnc_numeric_zero();
1425 }
#define PERR(format, args...)
Log a serious error.
Definition: qoflog.h:244
const char * gnc_commodity_get_printname(const gnc_commodity *cm)
Retrieve the 'print' name for the specified commodity.
gnc_numeric xaccSplitGetValue(const Split *split)
Returns the value of this split in the transaction's commodity.
Definition: Split.cpp:1955
gnc_commodity * xaccAccountGetCommodity(const Account *acc)
Get the account's commodity.
Definition: Account.cpp:3443
gnc_commodity * xaccTransGetCurrency(const Transaction *trans)
Returns the valuation commodity of this transaction.
gboolean gnc_commodity_equiv(const gnc_commodity *a, const gnc_commodity *b)
This routine returns TRUE if the two commodities are equivalent.
gnc_numeric xaccSplitGetAmount(const Split *split)
Returns the amount of the split in the account's commodity.
Definition: Split.cpp:1949

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

46 {
47  SCOPED_TRACE("");
48  auto mocksplit = gnc_mocksplit(split);
49  return mocksplit ? mocksplit->get_book() : nullptr;
50 }

◆ 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 1341 of file Split.cpp.

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

◆ 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 1653 of file Split.cpp.

1654 {
1655  static const char *split_const = nullptr;
1656  const Split *other_split;
1657 
1658  if (!get_corr_account_split(sa, &other_split))
1659  {
1660  if (!split_const)
1661  split_const = _("-- Split Transaction --");
1662 
1663  return g_strdup(split_const);
1664  }
1665  return gnc_account_get_full_name(other_split->acc);
1666 }
gchar * gnc_account_get_full_name(const Account *account)
The gnc_account_get_full_name routine returns the fully qualified name of the account using the given...
Definition: Account.cpp:3287

◆ xaccSplitGetDateReconciled()

time64 xaccSplitGetDateReconciled ( const Split *  split)

Retrieve the date when the Split was reconciled.

Definition at line 1854 of file Split.cpp.

1855 {
1856  return split ? split->date_reconciled : 0;
1857 }

◆ 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 1915 of file Split.cpp.

1916 {
1917  return split ? split->lot : nullptr;
1918 }

◆ xaccSplitGetMemo()

const char* xaccSplitGetMemo ( const Split *  split)

Returns the memo string.

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

100 {
101  SCOPED_TRACE("");
102  auto mocksplit = gnc_mocksplit(split);
103  return mocksplit ? mocksplit->get_memo() : "";
104 }

◆ 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 1335 of file Split.cpp.

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

◆ 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 144 of file gmock-Split.cpp.

145 {
146  SCOPED_TRACE("");
147  auto mocksplit = gnc_mocksplit(split);
148  return mocksplit ? mocksplit->get_other_split() : nullptr;
149 }

◆ xaccSplitGetParent()

Transaction* xaccSplitGetParent ( const Split *  split)

Returns the parent transaction of the split.

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

153 {
154  SCOPED_TRACE("");
155  auto mocksplit = gnc_mocksplit(split);
156  return mocksplit ? mocksplit->get_parent() : nullptr;
157 }

◆ xaccSplitGetReconcile()

char xaccSplitGetReconcile ( const Split *  split)

Returns the value of the reconcile flag.

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

115 {
116  SCOPED_TRACE("");
117  auto mocksplit = gnc_mocksplit(split);
118  return mocksplit ? mocksplit->get_reconcile() : VREC;
119 }
#define VREC
split is void
Definition: Split.h:75

◆ 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 1347 of file Split.cpp.

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

◆ 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 1961 of file Split.cpp.

1962 {
1963  gnc_numeric amt, val, price;
1964  if (!split) return gnc_numeric_create(0, 1);
1965 
1966 
1967  /* if amount == 0, return 0
1968  * otherwise return value/amount
1969  */
1970 
1971  amt = xaccSplitGetAmount(split);
1972  val = xaccSplitGetValue(split);
1973  if (gnc_numeric_zero_p(amt))
1974  return gnc_numeric_create(0, 1);
1975 
1976  price = gnc_numeric_div(val, amt,
1979 
1980  /* During random checks we can get some very weird prices. Let's
1981  * handle some overflow and other error conditions by returning
1982  * zero. But still print an error to let us know it happened.
1983  */
1984  if (gnc_numeric_check(price))
1985  {
1986  PERR("Computing share price failed (%d): [ %" G_GINT64_FORMAT " / %"
1987  G_GINT64_FORMAT " ] / [ %" G_GINT64_FORMAT " / %" G_GINT64_FORMAT " ]",
1988  gnc_numeric_check(price), val.num, val.denom, amt.num, amt.denom);
1989  return gnc_numeric_create(0, 1);
1990  }
1991 
1992  return price;
1993 }
gboolean gnc_numeric_zero_p(gnc_numeric a)
Returns 1 if the given gnc_numeric is 0 (zero), else returns 0.
#define PERR(format, args...)
Log a serious error.
Definition: qoflog.h:244
gnc_numeric gnc_numeric_div(gnc_numeric a, gnc_numeric b, gint64 denom, gint how)
Division.
gnc_numeric xaccSplitGetValue(const Split *split)
Returns the value of this split in the transaction's commodity.
Definition: Split.cpp:1955
Round to the nearest integer, rounding away from zero when there are two equidistant nearest integers...
Definition: gnc-numeric.h:167
GNCNumericErrorCode gnc_numeric_check(gnc_numeric in)
Check for error signal in value.
#define GNC_DENOM_AUTO
Values that can be passed as the 'denom' argument.
Definition: gnc-numeric.h:247
gnc_numeric xaccSplitGetAmount(const Split *split)
Returns the amount of the split in the account's commodity.
Definition: Split.cpp:1949

◆ 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 2005 of file Split.cpp.

2006 {
2007  if (!s) return nullptr;
2008 
2009  GValue v = G_VALUE_INIT;
2010  const char* type;
2011  qof_instance_get_kvp (QOF_INSTANCE (s), &v, 1, "split-type");
2012  type = G_VALUE_HOLDS_STRING (&v) ? g_value_get_string (&v) : nullptr;
2013  const char *rv;
2014  if (!type || !g_strcmp0 (type, split_type_normal))
2015  rv = split_type_normal;
2016  else if (!g_strcmp0 (type, split_type_stock_split))
2017  rv = split_type_stock_split;
2018  else
2019  {
2020  PERR ("unexpected split-type %s, reset to normal.", type);
2021  rv = split_type_normal;
2022  }
2023  g_value_unset (&v);
2024  return rv;
2025 }
#define PERR(format, args...)
Log a serious error.
Definition: qoflog.h:244
void qof_instance_get_kvp(QofInstance *, GValue *value, unsigned count,...)
Retrieves the contents of a KVP slot into a provided GValue.

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

85 {
86  SCOPED_TRACE("");
87  auto mocksplit = gnc_mocksplit(split);
88  return mocksplit ? mocksplit->get_value() : gnc_numeric_zero();
89 }

◆ xaccSplitIsPeerSplit()

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

Report if a split is a peer of this one.

Parameters
other_splitThe 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 2071 of file Split.cpp.

2072 {
2073  const GncGUID* guid;
2074 
2075  g_return_val_if_fail (split != nullptr, FALSE);
2076  g_return_val_if_fail (other_split != nullptr, FALSE);
2077 
2078  guid = qof_instance_get_guid (QOF_INSTANCE (other_split));
2079  return qof_instance_kvp_has_guid (QOF_INSTANCE (split), "lot-split",
2080  "peer_guid", guid);
2081 }
const GncGUID * qof_instance_get_guid(gconstpointer inst)
Return the GncGUID of this instance.
The type used to store guids in C.
Definition: guid.h:75

◆ 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 1103 of file Split.cpp.

1104 {
1105  QofCollection *col;
1106  if (!guid || !book) return nullptr;
1107  col = qof_book_get_collection (book, GNC_ID_SPLIT);
1108  return (Split *) qof_collection_lookup_entity (col, guid);
1109 }
QofInstance * qof_collection_lookup_entity(const QofCollection *col, const GncGUID *guid)
Find the entity going only from its guid.
Definition: qofid.cpp:212
QofCollection * qof_book_get_collection(const QofBook *book, QofIdType entity_type)
Return The table of entities of the given type.
Definition: qofbook.cpp:521

◆ 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 2030 of file Split.cpp.

2031 {
2032  GValue v = G_VALUE_INIT;
2033  xaccTransBeginEdit (s->parent);
2034 
2035  s->value = gnc_numeric_zero();
2036  g_value_init (&v, G_TYPE_STRING);
2037  g_value_set_static_string (&v, split_type_stock_split);
2038  qof_instance_set_kvp (QOF_INSTANCE (s), &v, 1, "split-type");
2039  SET_GAINS_VDIRTY(s);
2040  mark_split(s);
2041  qof_instance_set_dirty(QOF_INSTANCE(s));
2042  xaccTransCommitEdit(s->parent);
2043  g_value_unset (&v);
2044 }
void qof_instance_set_kvp(QofInstance *, GValue const *value, unsigned count,...)
Sets a KVP slot to a value from a GValue.
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...

◆ xaccSplitMergePeerSplits()

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

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

Parameters
other_splitThe split donating the peer splits.

Definition at line 2101 of file Split.cpp.

2102 {
2103  xaccTransBeginEdit (split->parent);
2104  qof_instance_kvp_merge_guids (QOF_INSTANCE (split),
2105  QOF_INSTANCE (other_split), "lot-split");
2106  mark_split (split);
2107  qof_instance_set_dirty (QOF_INSTANCE (split));
2108  xaccTransCommitEdit (split->parent);
2109 }
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...

◆ 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 1534 of file Split.cpp.

1535 {
1536  int retval;
1537  int comp;
1538  const char *da, *db;
1539  gboolean action_for_num;
1540 
1541  if (sa == sb) return 0;
1542  /* nothing is always less than something */
1543  if (!sa) return -1;
1544  if (!sb) return +1;
1545 
1546  /* sort in transaction order, but use split action rather than trans num
1547  * according to book option */
1549  (xaccSplitGetBook (sa));
1550  if (action_for_num)
1551  retval = xaccTransOrder_num_action (sa->parent, sa->action,
1552  sb->parent, sb->action);
1553  else
1554  retval = xaccTransOrder (sa->parent, sb->parent);
1555  if (retval) return retval;
1556 
1557  /* otherwise, sort on memo strings */
1558  da = sa->memo ? sa->memo : "";
1559  db = sb->memo ? sb->memo : "";
1560  retval = g_utf8_collate (da, db);
1561  if (retval)
1562  return retval;
1563 
1564  /* otherwise, sort on action strings */
1565  da = sa->action ? sa->action : "";
1566  db = sb->action ? sb->action : "";
1567  retval = g_utf8_collate (da, db);
1568  if (retval != 0)
1569  return retval;
1570 
1571  /* the reconciled flag ... */
1572  if (sa->reconciled < sb->reconciled) return -1;
1573  if (sa->reconciled > sb->reconciled) return +1;
1574 
1575  /* compare amounts */
1577  if (comp < 0) return -1;
1578  if (comp > 0) return +1;
1579 
1581  if (comp < 0) return -1;
1582  if (comp > 0) return +1;
1583 
1584  /* if dates differ, return */
1585  if (sa->date_reconciled < sb->date_reconciled)
1586  return -1;
1587  else if (sa->date_reconciled > sb->date_reconciled)
1588  return 1;
1589 
1590  /* else, sort on guid - keeps sort stable. */
1591  retval = qof_instance_guid_compare(sa, sb);
1592  if (retval) return retval;
1593 
1594  return 0;
1595 }
gboolean qof_book_use_split_action_for_num_field(const QofBook *book)
Returns TRUE if this book uses split action field as the &#39;Num&#39; field, FALSE if it uses transaction nu...
int gnc_numeric_compare(gnc_numeric a, gnc_numeric b)
Returns 1 if a>b, -1 if b>a, 0 if a == b.
QofBook * xaccSplitGetBook(const Split *split)
Returns the book of this split, i.e.
Definition: Split.cpp:1999
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.
gnc_numeric xaccSplitGetValue(const Split *split)
Returns the value of this split in the transaction&#39;s commodity.
Definition: Split.cpp:1955
gint qof_instance_guid_compare(gconstpointer ptr1, gconstpointer ptr2)
Compare the GncGUID values of two instances.
int xaccTransOrder(const Transaction *ta, const Transaction *tb)
The xaccTransOrder(ta,tb) method is useful for sorting.
gnc_numeric xaccSplitGetAmount(const Split *split)
Returns the amount of the split in the account&#39;s commodity.
Definition: Split.cpp:1949

◆ xaccSplitRemovePeerSplit()

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

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

Parameters
other_splitThe split whose guid to remove

Definition at line 2084 of file Split.cpp.

2085 {
2086  const GncGUID* guid;
2087 
2088  g_return_if_fail (split != nullptr);
2089  g_return_if_fail (other_split != nullptr);
2090 
2091  guid = qof_instance_get_guid (QOF_INSTANCE (other_split));
2092  xaccTransBeginEdit (split->parent);
2093  qof_instance_kvp_remove_guid (QOF_INSTANCE (split), "lot-split",
2094  "peer_guid", guid);
2095  mark_split (split);
2096  qof_instance_set_dirty (QOF_INSTANCE (split));
2097  xaccTransCommitEdit (split->parent);
2098 }
const GncGUID * qof_instance_get_guid(gconstpointer inst)
Return the GncGUID of this instance.
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
The type used to store guids in C.
Definition: guid.h:75

◆ 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 1781 of file Split.cpp.

1782 {
1783  if (!split || !actn) return;
1784  xaccTransBeginEdit (split->parent);
1785 
1786  CACHE_REPLACE(split->action, actn);
1787  qof_instance_set_dirty(QOF_INSTANCE(split));
1788  xaccTransCommitEdit(split->parent);
1789 
1790 }
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...

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

78 {
79  ASSERT_TRUE(GNC_IS_MOCKSPLIT(split));
80  gnc_mocksplit(split)->set_amount(amt);
81 }

◆ 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 1353 of file Split.cpp.

1355 {
1356  const gnc_commodity *currency;
1357  const gnc_commodity *commodity;
1358 
1359  if (!s) return;
1360  xaccTransBeginEdit (s->parent);
1361 
1362  if (!s->acc)
1363  {
1364  PERR ("split must have a parent account");
1365  return;
1366  }
1367 
1368  currency = xaccTransGetCurrency (s->parent);
1369  commodity = xaccAccountGetCommodity (s->acc);
1370 
1371  /* If the base_currency is the transaction's commodity ('currency'),
1372  * set the value. If it's the account commodity, set the
1373  * amount. If both, set both. */
1374  if (gnc_commodity_equiv(currency, base_currency))
1375  {
1376  if (gnc_commodity_equiv(commodity, base_currency))
1377  {
1378  s->amount = gnc_numeric_convert(value,
1379  get_commodity_denom(s),
1381  }
1382  s->value = gnc_numeric_convert(value,
1383  get_currency_denom(s),
1385  }
1386  else if (gnc_commodity_equiv(commodity, base_currency))
1387  {
1388  s->amount = gnc_numeric_convert(value, get_commodity_denom(s),
1390  }
1391  else
1392  {
1393  PERR ("inappropriate base currency %s "
1394  "given split currency=%s and commodity=%s\n",
1395  gnc_commodity_get_printname(base_currency),
1396  gnc_commodity_get_printname(currency),
1397  gnc_commodity_get_printname(commodity));
1398  return;
1399  }
1400 
1401  SET_GAINS_A_VDIRTY(s);
1402  mark_split (s);
1403  qof_instance_set_dirty(QOF_INSTANCE(s));
1404  xaccTransCommitEdit(s->parent);
1405 }
#define PERR(format, args...)
Log a serious error.
Definition: qoflog.h:244
gnc_numeric gnc_numeric_convert(gnc_numeric n, gint64 denom, gint how)
Change the denominator of a gnc_numeric value to the specified denominator under standard arguments &#39;...
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
const char * gnc_commodity_get_printname(const gnc_commodity *cm)
Retrieve the &#39;print&#39; name for the specified commodity.
gnc_commodity * xaccAccountGetCommodity(const Account *acc)
Get the account&#39;s commodity.
Definition: Account.cpp:3443
gnc_commodity * xaccTransGetCurrency(const Transaction *trans)
Returns the valuation commodity of this transaction.
Round to the nearest integer, rounding away from zero when there are two equidistant nearest integers...
Definition: gnc-numeric.h:167
gboolean gnc_commodity_equiv(const gnc_commodity *a, const gnc_commodity *b)
This routine returns TRUE if the two commodities are equivalent.

◆ 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 129 of file gmock-Split.cpp.

130 {
131  ASSERT_TRUE(GNC_IS_MOCKSPLIT(split));
132  gnc_mocksplit(split)->set_date_reconciled_secs(secs);
133 }

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

108 {
109  ASSERT_TRUE(GNC_IS_MOCKSPLIT(split));
110  gnc_mocksplit(split)->set_memo(memo);
111 }

◆ 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 122 of file gmock-Split.cpp.

123 {
124  ASSERT_TRUE(GNC_IS_MOCKSPLIT(split));
125  gnc_mocksplit(split)->set_reconcile(recn);
126 }

◆ 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 1219 of file Split.cpp.

1220 {
1221  if (!s) return;
1222 
1223  if (gnc_numeric_zero_p (price))
1224  return;
1225 
1226  ENTER (" ");
1227  xaccTransBeginEdit (s->parent);
1228 
1229  s->value = gnc_numeric_mul(xaccSplitGetAmount(s),
1230  price, get_currency_denom(s),
1232 
1233  SET_GAINS_VDIRTY(s);
1234  mark_split (s);
1235  qof_instance_set_dirty(QOF_INSTANCE(s));
1236  xaccTransCommitEdit(s->parent);
1237  LEAVE ("");
1238 }
gboolean gnc_numeric_zero_p(gnc_numeric a)
Returns 1 if the given gnc_numeric is 0 (zero), else returns 0.
#define ENTER(format, args...)
Print a function entry debugging message.
Definition: qoflog.h:272
gnc_numeric gnc_numeric_mul(gnc_numeric a, gnc_numeric b, gint64 denom, gint how)
Multiply a times b, returning the product.
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
#define LEAVE(format, args...)
Print a function exit debugging message.
Definition: qoflog.h:282
Round to the nearest integer, rounding away from zero when there are two equidistant nearest integers...
Definition: gnc-numeric.h:167
gnc_numeric xaccSplitGetAmount(const Split *split)
Returns the amount of the split in the account&#39;s commodity.
Definition: Split.cpp:1949

◆ 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 1191 of file Split.cpp.

1192 {
1193  if (!s) return;
1194  ENTER (" ");
1195  xaccTransBeginEdit (s->parent);
1196 
1197  s->amount = gnc_numeric_convert(amt, get_commodity_denom(s),
1199  s->value = gnc_numeric_mul(s->amount, price,
1200  get_currency_denom(s), GNC_HOW_RND_ROUND_HALF_UP);
1201 
1202  SET_GAINS_A_VDIRTY(s);
1203  mark_split (s);
1204  qof_instance_set_dirty(QOF_INSTANCE(s));
1205  xaccTransCommitEdit(s->parent);
1206  LEAVE ("");
1207 }
#define ENTER(format, args...)
Print a function entry debugging message.
Definition: qoflog.h:272
gnc_numeric gnc_numeric_convert(gnc_numeric n, gint64 denom, gint how)
Change the denominator of a gnc_numeric value to the specified denominator under standard arguments &#39;...
gnc_numeric gnc_numeric_mul(gnc_numeric a, gnc_numeric b, gint64 denom, gint how)
Multiply a times b, returning the product.
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
#define LEAVE(format, args...)
Print a function exit debugging message.
Definition: qoflog.h:282
Round to the nearest integer, rounding away from zero when there are two equidistant nearest integers...
Definition: gnc-numeric.h:167

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

93 {
94  ASSERT_TRUE(GNC_IS_MOCKSPLIT(split));
95  gnc_mocksplit(split)->set_value(val);
96 }

◆ xaccSplitVoidFormerAmount()

gnc_numeric xaccSplitVoidFormerAmount ( const Split *  split)

Returns the original pre-void amount of a split.

Parameters
splitThe 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 2154 of file Split.cpp.

2155 {
2156  GValue v = G_VALUE_INIT;
2157  gnc_numeric *num = nullptr;
2158  gnc_numeric retval;
2159  g_return_val_if_fail(split, gnc_numeric_zero());
2160  qof_instance_get_kvp (QOF_INSTANCE (split), &v, 1, void_former_amt_str);
2161  if (G_VALUE_HOLDS_BOXED (&v))
2162  num = (gnc_numeric*)g_value_get_boxed (&v);
2163  retval = num ? *num : gnc_numeric_zero();
2164  g_value_unset (&v);
2165  return retval;
2166 }
void qof_instance_get_kvp(QofInstance *, GValue *value, unsigned count,...)
Retrieves the contents of a KVP slot into a provided GValue.

◆ xaccSplitVoidFormerValue()

gnc_numeric xaccSplitVoidFormerValue ( const Split *  split)

Returns the original pre-void value of a split.

Parameters
splitThe 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 2169 of file Split.cpp.

2170 {
2171  GValue v = G_VALUE_INIT;
2172  gnc_numeric *num = nullptr;
2173  gnc_numeric retval;
2174  g_return_val_if_fail(split, gnc_numeric_zero());
2175  qof_instance_get_kvp (QOF_INSTANCE (split), &v, 1, void_former_val_str);
2176  if (G_VALUE_HOLDS_BOXED (&v))
2177  num = (gnc_numeric*)g_value_get_boxed (&v);
2178  retval = num ? *num : gnc_numeric_zero();
2179  g_value_unset (&v);
2180  return retval;
2181 }
void qof_instance_get_kvp(QofInstance *, GValue *value, unsigned count,...)
Retrieves the contents of a KVP slot into a provided GValue.

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

36 {
37  ASSERT_TRUE(GNC_IS_MOCKTRANSACTION(trans));
38  gnc_mocktransaction(trans)->begin_edit();
39 }

◆ 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 2206 of file Transaction.cpp.

2207 {
2208  xaccTransBeginEdit(trans);
2209  /* We only own the splits that still think they belong to us. This is done
2210  in 2 steps. In the first, the splits are marked as being destroyed, but they
2211  are not destroyed yet. In the second, the destruction is committed which will
2212  do the actual destruction. If both steps are done for a split before they are
2213  done for the next split, then a split will still be on the split list after it
2214  has been freed. This can cause other parts of the code (e.g. in xaccSplitDestroy())
2215  to reference the split after it has been freed. */
2216  for (auto node = trans->splits; node; node = node->next)
2217  {
2218  auto s = GNC_SPLIT(node->data);
2219  if (s && s->parent == trans)
2220  {
2221  xaccSplitDestroy(s);
2222  }
2223  }
2224  for (auto node = trans->splits; node; node = node->next)
2225  {
2226  auto s = GNC_SPLIT(node->data);
2227  if (s && s->parent == trans)
2228  {
2229  xaccSplitCommitEdit(s);
2230  }
2231  }
2232  g_list_free (trans->splits);
2233  trans->splits = nullptr;
2234 
2235  xaccTransCommitEdit(trans);
2236 }
gboolean xaccSplitDestroy(Split *split)
Destructor.
Definition: Split.cpp:1504
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...

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

43 {
44  ASSERT_TRUE(GNC_IS_MOCKTRANSACTION(trans));
45  gnc_mocktransaction(trans)->commit_edit();
46 }

◆ 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 745 of file Transaction.cpp.

747 {
748  gboolean change_accounts = FALSE;
749  GList *node;
750 
751  if (!from_trans || !to_trans)
752  return;
753 
754  change_accounts = from_acc && GNC_IS_ACCOUNT(to_acc) && from_acc != to_acc;
755  xaccTransBeginEdit(to_trans);
756 
757  xaccTransClearSplits(to_trans);
758  xaccTransSetCurrency(to_trans, xaccTransGetCurrency(from_trans));
759  xaccTransSetDescription(to_trans, xaccTransGetDescription(from_trans));
760 
761  if ((xaccTransGetNum(to_trans) == nullptr) || (g_strcmp0 (xaccTransGetNum(to_trans), "") == 0))
762  xaccTransSetNum(to_trans, xaccTransGetNum(from_trans));
763 
764  xaccTransSetNotes(to_trans, xaccTransGetNotes(from_trans));
765  xaccTransSetDocLink(to_trans, xaccTransGetDocLink (from_trans));
766  if(!no_date)
767  {
768  xaccTransSetDatePostedSecs(to_trans, xaccTransRetDatePosted (from_trans));
769  }
770 
771  /* Each new split will be parented to 'to' */
772  for (node = from_trans->splits; node; node = node->next)
773  {
774  Split *new_split = xaccMallocSplit( qof_instance_get_book(QOF_INSTANCE(from_trans)));
775  xaccSplitCopyOnto(GNC_SPLIT(node->data), new_split);
776  if (change_accounts && xaccSplitGetAccount(GNC_SPLIT(node->data)) == from_acc)
777  xaccSplitSetAccount(new_split, to_acc);
778  xaccSplitSetParent(new_split, to_trans);
779  }
780  xaccTransCommitEdit(to_trans);
781 }
void xaccTransClearSplits(Transaction *trans)
Remove all splits from the transaction.
QofBook * qof_instance_get_book(gconstpointer inst)
Return the book pointer.
void xaccTransSetNotes(Transaction *trans, const char *notes)
Sets the transaction Notes.
void xaccSplitCopyOnto(const Split *from_split, Split *to_split)
This is really a helper for xaccTransCopyOnto.
Definition: Split.cpp:638
void xaccTransSetDescription(Transaction *trans, const char *desc)
Sets the transaction Description.
void xaccTransSetNum(Transaction *trans, const char *xnum)
Sets the transaction Number (or ID) field; rather than use this function directly, see &#39;gnc_set_num_action&#39; 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 * xaccTransGetNum(const Transaction *trans)
Gets the transaction Number (or ID) field; rather than use this function directly, see &#39;gnc_get_num_action&#39; and &#39;gnc_get_action_num&#39; 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 * xaccTransGetDocLink(const Transaction *trans)
Gets the transaction Document Link.
void xaccTransSetCurrency(Transaction *trans, gnc_commodity *curr)
Set a new currency on a transaction.
const char * xaccTransGetNotes(const Transaction *trans)
Gets the transaction Notes.
time64 xaccTransRetDatePosted(const Transaction *trans)
Retrieve the posted date of the transaction.
const char * xaccTransGetDescription(const Transaction *trans)
Gets the transaction Description.
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Split * xaccMallocSplit(QofBook *book)
Constructor.
Definition: gmock-Split.cpp:37
void xaccTransSetDatePostedSecs(Transaction *trans, time64 secs)
The xaccTransSetDatePostedSecs() method will modify the posted date of the transaction, specified by a time64 (see ctime(3)).
Account * xaccSplitGetAccount(const Split *split)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: gmock-Split.cpp:53
gnc_commodity * xaccTransGetCurrency(const Transaction *trans)
Returns the valuation commodity of this transaction.
void xaccTransSetDocLink(Transaction *trans, const char *doclink)
Sets the transaction Document Link.

◆ 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 705 of file Transaction.cpp.

706 {
707  Transaction *to_trans;
708 
709  if (!from_trans)
710  return nullptr;
711 
712  to_trans = dupe_trans(from_trans);
713  return to_trans;
714 }

◆ xaccTransCountSplits()

int xaccTransCountSplits ( const Transaction *  trans)

Returns the number of splits in this transaction.

Definition at line 2342 of file Transaction.cpp.

2343 {
2344  gint i = 0;
2345  g_return_val_if_fail (trans != nullptr, 0);
2346  FOR_EACH_SPLIT(trans, i++);
2347  return i;
2348 }

◆ 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
transthe transaction to destroy

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

151 {
152  ASSERT_TRUE(GNC_IS_MOCKTRANSACTION(trans));
153  gnc_mocktransaction(trans)->destroy();
154 }

◆ xaccTransEqual()

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

Equality.

Parameters
taFirst transaction to compare
tbSecond transaction to compare
check_guidsIf 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_splitsIf TRUE, after checking the transaction data structures for equality, also check all splits attached to the transaction for equality.
check_balancesIf 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_orderedIf 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 850 of file Transaction.cpp.

855 {
856  gboolean same_book;
857 
858  if (!ta && !tb) return TRUE; /* Arguable. FALSE may be better. */
859 
860  if (!ta || !tb)
861  {
862  PINFO ("one is nullptr");
863  return FALSE;
864  }
865 
866  if (ta == tb) return TRUE;
867 
868  same_book = qof_instance_get_book(QOF_INSTANCE(ta)) == qof_instance_get_book(QOF_INSTANCE(tb));
869 
870  if (check_guids)
871  {
872  if (qof_instance_guid_compare(ta, tb) != 0)
873  {
874  PINFO ("GUIDs differ");
875  return FALSE;
876  }
877  }
878 
879  if (!gnc_commodity_equal(ta->common_currency, tb->common_currency))
880  {
881  PINFO ("commodities differ %s vs %s",
882  gnc_commodity_get_unique_name (ta->common_currency),
883  gnc_commodity_get_unique_name (tb->common_currency));
884  return FALSE;
885  }
886 
887  if (ta->date_entered != tb->date_entered)
888  {
889  char buf1[100];
890  char buf2[100];
891 
892  (void)gnc_time64_to_iso8601_buff(ta->date_entered, buf1);
893  (void)gnc_time64_to_iso8601_buff(tb->date_entered, buf2);
894  PINFO ("date entered differs: '%s' vs '%s'", buf1, buf2);
895  return FALSE;
896  }
897 
898  if (ta->date_posted != tb->date_posted)
899  {
900  char buf1[100];
901  char buf2[100];
902 
903  (void)gnc_time64_to_iso8601_buff(ta->date_posted, buf1);
904  (void)gnc_time64_to_iso8601_buff(tb->date_posted, buf2);
905  PINFO ("date posted differs: '%s' vs '%s'", buf1, buf2);
906  return FALSE;
907  }
908 
909  /* If the same book, since we use cached strings, we can just compare pointer
910  * equality for num and description
911  */
912  if ((same_book && ta->num != tb->num) || (!same_book && g_strcmp0(ta->num, tb->num) != 0))
913  {
914  PINFO ("num differs: %s vs %s", ta->num, tb->num);
915  return FALSE;
916  }
917 
918  if ((same_book && ta->description != tb->description)
919  || (!same_book && g_strcmp0(ta->description, tb->description)))
920  {
921  PINFO ("descriptions differ: %s vs %s", ta->description, tb->description);
922  return FALSE;
923  }
924 
925  if (qof_instance_compare_kvp (QOF_INSTANCE (ta), QOF_INSTANCE (tb)) != 0)
926  {
927  char *frame_a;
928  char *frame_b;
929 
930  frame_a = qof_instance_kvp_as_string (QOF_INSTANCE (ta));
931  frame_b = qof_instance_kvp_as_string (QOF_INSTANCE (tb));
932 
933 
934  PINFO ("kvp frames differ:\n%s\n\nvs\n\n%s", frame_a, frame_b);
935 
936  g_free (frame_a);
937  g_free (frame_b);
938 
939  return FALSE;
940  }
941 
942  if (check_splits)
943  {
944  if ((!ta->splits && tb->splits) || (!tb->splits && ta->splits))
945  {
946  PINFO ("only one has splits");
947  return FALSE;
948  }
949 
950  if (ta->splits && tb->splits)
951  {
952  GList *node_a, *node_b;
953 
954  for (node_a = ta->splits, node_b = tb->splits;
955  node_a;
956  node_a = node_a->next, node_b = node_b->next)
957  {
958  Split *split_a = GNC_SPLIT(node_a->data);
959  Split *split_b;
960 
961  /* don't presume that the splits are in the same order */
962  if (!assume_ordered)
963  node_b = g_list_find_custom (tb->splits, split_a,
964  compare_split_guids);
965 
966  if (!node_b)
967  {
968  gchar guidstr[GUID_ENCODING_LENGTH+1];
969  guid_to_string_buff (xaccSplitGetGUID (split_a),guidstr);
970 
971  PINFO ("first has split %s and second does not",guidstr);
972  return FALSE;
973  }
974 
975  split_b = GNC_SPLIT(node_b->data);
976 
977  if (!xaccSplitEqual (split_a, split_b, check_guids, check_balances,
978  FALSE))
979  {
980  char str_a[GUID_ENCODING_LENGTH + 1];
981  char str_b[GUID_ENCODING_LENGTH + 1];
982 
983  guid_to_string_buff (xaccSplitGetGUID (split_a), str_a);
984  guid_to_string_buff (xaccSplitGetGUID (split_b), str_b);
985 
986  PINFO ("splits %s and %s differ", str_a, str_b);
987  return FALSE;
988  }
989  }
990 
991  if (g_list_length (ta->splits) != g_list_length (tb->splits))
992  {
993  PINFO ("different number of splits");
994  return FALSE;
995  }
996  }
997  }
998 
999  return TRUE;
1000 }
QofBook * qof_instance_get_book(gconstpointer inst)
Return the book pointer.
#define PINFO(format, args...)
Print an informational note.
Definition: qoflog.h:256
gboolean gnc_commodity_equal(const gnc_commodity *a, const gnc_commodity *b)
This routine returns TRUE if the two commodities are equal.
gchar * guid_to_string_buff(const GncGUID *guid, gchar *str)
The guid_to_string_buff() routine puts a null-terminated string encoding of the id into the memory po...
Definition: guid.cpp:173
gboolean xaccSplitEqual(const Split *sa, const Split *sb, gboolean check_guids, gboolean check_balances, gboolean check_txn_splits)
Equality.
Definition: Split.cpp:801
#define GUID_ENCODING_LENGTH
Number of characters needed to encode a guid as a string not including the null terminator.
Definition: guid.h:84
#define xaccSplitGetGUID(X)
Definition: Split.h:555
gint qof_instance_guid_compare(gconstpointer ptr1, gconstpointer ptr2)
Compare the GncGUID values of two instances.
const char * gnc_commodity_get_unique_name(const gnc_commodity *cm)
Retrieve the &#39;unique&#39; name for the specified commodity.
char * gnc_time64_to_iso8601_buff(time64 time, char *buff)
The gnc_time64_to_iso8601_buff() routine takes the input UTC time64 value and prints it as an ISO-860...
Definition: gnc-date.cpp:1139

◆ xaccTransGetAccountAmount()

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

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

Definition at line 1180 of file Transaction.cpp.

1181 {
1182  gnc_numeric total = gnc_numeric_zero ();
1183  if (!trans || !acc) return total;
1184 
1185  total = gnc_numeric_convert (total, xaccAccountGetCommoditySCU (acc),
1187  FOR_EACH_SPLIT(trans, if (acc == xaccSplitGetAccount(s))
1188  total = gnc_numeric_add_fixed(
1189  total, xaccSplitGetAmount(s)));
1190  return total;
1191 }
int xaccAccountGetCommoditySCU(const Account *acc)
Return the SCU for the account.
Definition: Account.cpp:2680
gnc_numeric gnc_numeric_convert(gnc_numeric n, gint64 denom, gint how)
Change the denominator of a gnc_numeric value to the specified denominator under standard arguments &#39;...
Account * xaccSplitGetAccount(const Split *split)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: gmock-Split.cpp:53
Round to the nearest integer, rounding away from zero when there are two equidistant nearest integers...
Definition: gnc-numeric.h:167
gnc_numeric xaccSplitGetAmount(const Split *split)
Returns the amount of the split in the account&#39;s commodity.
Definition: gmock-Split.cpp:69

◆ 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 1304 of file Transaction.cpp.

1306 {
1307  GList *node;
1308  Split *last_split = nullptr;
1309 
1310  // Not really the appropriate error value.
1311  g_return_val_if_fail(account && trans, gnc_numeric_error(GNC_ERROR_ARG));
1312 
1313  for (node = trans->splits; node; node = node->next)
1314  {
1315  Split *split = GNC_SPLIT(node->data);
1316 
1317  if (!xaccTransStillHasSplit(trans, split))
1318  continue;
1319  if (xaccSplitGetAccount(split) != account)
1320  continue;
1321 
1322  if (!last_split)
1323  {
1324  last_split = split;
1325  continue;
1326  }
1327 
1328  /* This test needs to correspond to the comparison function used when
1329  sorting the splits for computing the running balance. */
1330  if (xaccSplitOrder (last_split, split) < 0)
1331  last_split = split;
1332  }
1333 
1334  return xaccSplitGetBalance (last_split);
1335 }
gint xaccSplitOrder(const Split *sa, const Split *sb)
The xaccSplitOrder(sa,sb) method is useful for sorting.
Definition: Split.cpp:1534
gnc_numeric xaccSplitGetBalance(const Split *s)
Returns the running balance up to and including the indicated split.
Definition: Split.cpp:1329
gnc_numeric gnc_numeric_error(GNCNumericErrorCode error_code)
Create a gnc_numeric object that signals the error condition noted by error_code, rather than a numbe...
Argument is not a valid number.
Definition: gnc-numeric.h:226
Account * xaccSplitGetAccount(const Split *split)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: gmock-Split.cpp:53

◆ 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 1164 of file Transaction.cpp.

1166 {
1167  gnc_numeric total = gnc_numeric_zero ();
1168  if (!trans || !acc) return total;
1169 
1170  FOR_EACH_SPLIT(trans, if (acc == xaccSplitGetAccount(s))
1171 {
1172  total = gnc_numeric_add (total, xaccSplitGetValue (s),
1175  });
1176  return total;
1177 }
gnc_numeric gnc_numeric_add(gnc_numeric a, gnc_numeric b, gint64 denom, gint how)
Return a+b.
Use any denominator which gives an exactly correct ratio of numerator to denominator.
Definition: gnc-numeric.h:190
gnc_numeric xaccSplitGetValue(const Split *split)
Returns the value of this split in the transaction&#39;s commodity.
Definition: gmock-Split.cpp:84
Account * xaccSplitGetAccount(const Split *split)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: gmock-Split.cpp:53
#define GNC_DENOM_AUTO
Values that can be passed as the &#39;denom&#39; argument.
Definition: gnc-numeric.h:247

◆ 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
transThe transaction
strictThis 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 2279 of file Transaction.cpp.

2280 {
2281  GList *apar_splits = nullptr;
2282  if (!trans) return nullptr;
2283 
2284  FOR_EACH_SPLIT (trans,
2285  const Account *account = xaccSplitGetAccount(s);
2286  if (account && xaccAccountIsAPARType(xaccAccountGetType(account)))
2287  {
2288 
2289  if (!strict)
2290  apar_splits = g_list_prepend (apar_splits, s);
2291  else
2292  {
2293  GncOwner owner;
2294  GNCLot *lot = xaccSplitGetLot(s);
2295  if (lot &&
2296  (gncInvoiceGetInvoiceFromLot (lot) ||
2297  gncOwnerGetOwnerFromLot (lot, &owner)))
2298  apar_splits = g_list_prepend (apar_splits, s);
2299  }
2300  }
2301  );
2302 
2303  apar_splits = g_list_reverse (apar_splits);
2304  return apar_splits;
2305 }
GNCAccountType xaccAccountGetType(const Account *acc)
Returns the account&#39;s account type.
Definition: Account.cpp:3258
gboolean gncOwnerGetOwnerFromLot(GNCLot *lot, GncOwner *owner)
Get the owner from the lot.
Definition: gncOwner.c:636
gboolean xaccAccountIsAPARType(GNCAccountType t)
Convenience function to check if the account is a valid business account type (meaning an Accounts Pa...
Definition: Account.cpp:4693
GncInvoice * gncInvoiceGetInvoiceFromLot(GNCLot *lot)
Given a LOT, find and return the Invoice attached to the lot.
Definition: gncInvoice.c:1289
Account * xaccSplitGetAccount(const Split *split)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: gmock-Split.cpp:53
GNCLot * xaccSplitGetLot(const Split *split)
Returns the pointer to the debited/credited Lot where this split belongs to, or NULL if it doesn&#39;t be...
Definition: Split.cpp:1915

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

135 {
136  SCOPED_TRACE("");
137  auto mocktrans = gnc_mocktransaction(trans);
138  return mocktrans ? mocktrans->get_currency() : nullptr;
139 }

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

74 {
75  SCOPED_TRACE("");
76  auto mocktrans = gnc_mocktransaction(trans);
77  return mocktrans ? mocktrans->get_date() : 0;
78 }

◆ 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 2416 of file Transaction.cpp.

2417 {
2418  return trans ? trans->date_entered : 0;
2419 }

◆ 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 2429 of file Transaction.cpp.

2430 {
2431  GDate result;
2432  g_date_clear (&result, 1);
2433  if (trans)
2434  {
2435  /* Can we look up this value in the kvp slot? If yes, use it
2436  * from there because it doesn't suffer from time zone
2437  * shifts. */
2438  GValue v = G_VALUE_INIT;
2439  qof_instance_get_kvp (QOF_INSTANCE (trans), &v, 1, TRANS_DATE_POSTED);
2440  if (G_VALUE_HOLDS_BOXED (&v))
2441  result = *(GDate*)g_value_get_boxed (&v);
2442  g_value_unset (&v);
2443  if (! g_date_valid (&result) || gdate_to_time64 (result) == INT64_MAX)
2444  {
2445  /* Well, this txn doesn't have a valid GDate saved in a slot.
2446  * time64_to_gdate() uses local time and we want UTC so we have
2447  * to write it out.
2448  */
2449  time64 time = xaccTransGetDate(trans);
2450  struct tm *stm = gnc_gmtime(&time);
2451  if (stm)
2452  {
2453  g_date_set_dmy(&result, stm->tm_mday,
2454  (GDateMonth)(stm->tm_mon + 1),
2455  stm->tm_year + 1900);
2456  free(stm);
2457  }
2458  }
2459  }
2460  return result;
2461 }
time64 xaccTransGetDate(const Transaction *trans)
Retrieve the posted date of the transaction.
void qof_instance_get_kvp(QofInstance *, GValue *value, unsigned count,...)
Retrieves the contents of a KVP slot into a provided GValue.
time64 gdate_to_time64(GDate d)
Turns a GDate into a time64, returning the first second of the day.
Definition: gnc-date.cpp:1252
struct tm * gnc_gmtime(const time64 *secs)
fill out a time struct from a 64-bit time value
Definition: gnc-date.cpp:177
gint64 time64
Most systems that are currently maintained, including Microsoft Windows, BSD-derived Unixes and Linux...
Definition: gnc-date.h:87

◆ 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
transThe transaction
strictThis 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 2318 of file Transaction.cpp.

2319 {
2320  FOR_EACH_SPLIT (trans,
2321  const Account *account = xaccSplitGetAccount(s);
2322  if (account && xaccAccountIsAPARType(xaccAccountGetType(account)))
2323  {
2324  GNCLot *lot;
2325  GncOwner owner;
2326 
2327  if (!strict)
2328  return s;
2329 
2330  lot = xaccSplitGetLot(s);
2331  if (lot &&
2332  (gncInvoiceGetInvoiceFromLot (lot) ||
2333  gncOwnerGetOwnerFromLot (lot, &owner)))
2334  return s;
2335  }
2336  );
2337 
2338  return nullptr;
2339 }
GNCAccountType xaccAccountGetType(const Account *acc)
Returns the account&#39;s account type.
Definition: Account.cpp:3258
gboolean gncOwnerGetOwnerFromLot(GNCLot *lot, GncOwner *owner)
Get the owner from the lot.
Definition: gncOwner.c:636
gboolean xaccAccountIsAPARType(GNCAccountType t)
Convenience function to check if the account is a valid business account type (meaning an Accounts Pa...
Definition: Account.cpp:4693
GncInvoice * gncInvoiceGetInvoiceFromLot(GNCLot *lot)
Given a LOT, find and return the Invoice attached to the lot.
Definition: gncInvoice.c:1289
Account * xaccSplitGetAccount(const Split *split)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: gmock-Split.cpp:53
GNCLot * xaccSplitGetLot(const Split *split)
Returns the pointer to the debited/credited Lot where this split belongs to, or NULL if it doesn&#39;t be...
Definition: Split.cpp:1915

◆ 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
transThe transaction

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

Definition at line 2307 of file Transaction.cpp.

2308 {
2309  FOR_EACH_SPLIT (trans,
2310  const Account *account = xaccSplitGetAccount(s);
2311  if (account && gncBusinessIsPaymentAcctType(xaccAccountGetType(account)))
2312  return s;
2313  );
2314 
2315  return nullptr;
2316 }
GNCAccountType xaccAccountGetType(const Account *acc)
Returns the account&#39;s account type.
Definition: Account.cpp:3258
gboolean gncBusinessIsPaymentAcctType(GNCAccountType type)
Returns whether the given account type is a valid type to use in business payments.
Definition: gncBusiness.c:92
Account * xaccSplitGetAccount(const Split *split)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: gmock-Split.cpp:53

◆ 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 1046 of file Transaction.cpp.

1047 {
1048  /* imbal_value is used if either (1) the transaction has a non currency
1049  split or (2) all the splits are in the same currency. If there are
1050  no non-currency splits and not all splits are in the same currency then
1051  imbal_list is used to compute the imbalance. */
1052  MonetaryList *imbal_list = nullptr;
1053  gnc_numeric imbal_value = gnc_numeric_zero();
1054  gboolean trading_accts;
1055 
1056  if (!trans) return imbal_list;
1057 
1058  ENTER("(trans=%p)", trans);
1059 
1060  trading_accts = xaccTransUseTradingAccounts (trans);
1061 
1062  /* If using trading accounts and there is at least one split that is not
1063  in the transaction currency or a split that has a price or exchange
1064  rate other than 1, then compute the balance in each commodity in the
1065  transaction. Otherwise (all splits are in the transaction's currency)
1066  then compute the balance using the value fields.
1067 
1068  Optimize for the common case of only one currency and a balanced
1069  transaction. */
1070  FOR_EACH_SPLIT(trans,
1071  {
1072  gnc_commodity *commodity;
1074  if (trading_accts &&
1075  (imbal_list ||
1076  ! gnc_commodity_equiv(commodity, trans->common_currency) ||
1078  {
1079  /* Need to use (or already are using) a list of imbalances in each of
1080  the currencies used in the transaction. */
1081  if (! imbal_list)
1082  {
1083  /* All previous splits have been in the transaction's common
1084  currency, so imbal_value is in this currency. */
1085  imbal_list = gnc_monetary_list_add_value(imbal_list,
1086  trans->common_currency,
1087  imbal_value);
1088  }
1089  imbal_list = gnc_monetary_list_add_value(imbal_list, commodity,
1090  xaccSplitGetAmount(s));
1091  }
1092 
1093  /* Add it to the value accumulator in case we need it. */
1094  imbal_value = gnc_numeric_add(imbal_value, xaccSplitGetValue(s),
1096  } );
1097 
1098 
1099  if (!imbal_list && !gnc_numeric_zero_p(imbal_value))
1100  {
1101  /* Not balanced and no list, create one. If we found multiple currencies
1102  and no non-currency commodity then imbal_list will already exist and
1103  we won't get here. */
1104  imbal_list = gnc_monetary_list_add_value(imbal_list,
1105  trans->common_currency,
1106  imbal_value);
1107  }
1108 
1109  /* Delete all the zero entries from the list, perhaps leaving an
1110  empty list */
1111  imbal_list = gnc_monetary_list_delete_zeros(imbal_list);
1112 
1113  LEAVE("(trans=%p), imbal=%p", trans, imbal_list);
1114  return imbal_list;
1115 }
gboolean gnc_numeric_equal(gnc_numeric a, gnc_numeric b)
Equivalence predicate: Returns TRUE (1) if a and b represent the same number.
gboolean xaccTransUseTradingAccounts(const Transaction *trans)
Determine whether this transaction should use commodity trading accounts.
gnc_numeric gnc_numeric_add(gnc_numeric a, gnc_numeric b, gint64 denom, gint how)
Return a+b.
gboolean gnc_numeric_zero_p(gnc_numeric a)
Returns 1 if the given gnc_numeric is 0 (zero), else returns 0.
Use any denominator which gives an exactly correct ratio of numerator to denominator.
Definition: gnc-numeric.h:190
#define ENTER(format, args...)
Print a function entry debugging message.
Definition: qoflog.h:272
MonetaryList * gnc_monetary_list_delete_zeros(MonetaryList *list)
Delete all entries in the list that have zero value.
gnc_numeric xaccSplitGetValue(const Split *split)
Returns the value of this split in the transaction&#39;s commodity.
Definition: gmock-Split.cpp:84
Account * xaccSplitGetAccount(const Split *split)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: gmock-Split.cpp:53
gnc_commodity * xaccAccountGetCommodity(const Account *acc)
Get the account&#39;s commodity.
Definition: Account.cpp:3443
#define LEAVE(format, args...)
Print a function exit debugging message.
Definition: qoflog.h:282
#define GNC_DENOM_AUTO
Values that can be passed as the &#39;denom&#39; argument.
Definition: gnc-numeric.h:247
gboolean gnc_commodity_equiv(const gnc_commodity *a, const gnc_commodity *b)
This routine returns TRUE if the two commodities are equivalent.
gnc_numeric xaccSplitGetAmount(const Split *split)
Returns the amount of the split in the account&#39;s commodity.
Definition: gmock-Split.cpp:69

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

119 {
120  SCOPED_TRACE("");
121  auto mocktrans = gnc_mocktransaction(trans);
122  return mocktrans ? mocktrans->get_imbalance_value() : gnc_numeric_zero();
123 }

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

104 {
105  SCOPED_TRACE("");
106  auto mocktrans = gnc_mocktransaction(trans);
107  return mocktrans ? mocktrans->get_notes() : "";
108 }

◆ 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
transThe transaction
Returns
The list of splits. This list must be freed when you are done with it.

Definition at line 2265 of file Transaction.cpp.

2266 {
2267  GList *pay_splits = nullptr;
2268  FOR_EACH_SPLIT (trans,
2269  const Account *account = xaccSplitGetAccount(s);
2270  if (account && gncBusinessIsPaymentAcctType(xaccAccountGetType(account)))
2271  pay_splits = g_list_prepend (pay_splits, s);
2272  );
2273 
2274  pay_splits = g_list_reverse (pay_splits);
2275  return pay_splits;
2276 }
GNCAccountType xaccAccountGetType(const Account *acc)
Returns the account&#39;s account type.
Definition: Account.cpp:3258
gboolean gncBusinessIsPaymentAcctType(GNCAccountType type)
Returns whether the given account type is a valid type to use in business payments.
Definition: gncBusiness.c:92
Account * xaccSplitGetAccount(const Split *split)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: gmock-Split.cpp:53

◆ 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 2526 of file Transaction.cpp.

2527 {
2528  if (!trans)
2529  return nullptr;
2530 
2531  GValue v = G_VALUE_INIT;
2532  qof_instance_get_kvp (QOF_INSTANCE(trans), &v, 1, TRANS_READ_ONLY_REASON);
2533  const char *readonly_reason = G_VALUE_HOLDS_STRING (&v) ?
2534  g_value_get_string (&v) : nullptr;
2535  g_value_unset (&v);
2536  return readonly_reason;
2537 }
void qof_instance_get_kvp(QofInstance *, GValue *value, unsigned count,...)
Retrieves the contents of a KVP slot into a provided GValue.

◆ xaccTransGetReversedBy()

Transaction* xaccTransGetReversedBy ( const Transaction *  trans)

Returns the transaction that reversed the given transaction.

Parameters
transa 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 2857 of file Transaction.cpp.

2858 {
2859  GValue v = G_VALUE_INIT;
2860  Transaction *retval = nullptr;
2861  g_return_val_if_fail(trans, nullptr);
2862  qof_instance_get_kvp (QOF_INSTANCE(trans), &v, 1, TRANS_REVERSED_BY);
2863  if (G_VALUE_HOLDS_BOXED (&v))
2864  {
2865  GncGUID* guid = static_cast<GncGUID*>(g_value_get_boxed (&v));
2866  retval = xaccTransLookup(guid, qof_instance_get_book (trans));
2867  }
2868  g_value_unset (&v);
2869  return retval;
2870 }
QofBook * qof_instance_get_book(gconstpointer inst)
Return the book pointer.
void qof_instance_get_kvp(QofInstance *, GValue *value, unsigned count,...)
Retrieves the contents of a KVP slot into a provided GValue.
Transaction * xaccTransLookup(const GncGUID *guid, QofBook *book)
The xaccTransLookup() subroutine will return the transaction associated with the given id...
The type used to store guids in C.
Definition: guid.h:75

◆ 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
transThe transaction
iThe 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.

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

◆ xaccTransGetSplitList()

SplitList* xaccTransGetSplitList ( const Transaction *  trans)

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

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

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

◆ 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 2487 of file Transaction.cpp.

2488 {
2489  gboolean has_nonAPAR_split = FALSE;
2490 
2491  if (!trans) return TXN_TYPE_NONE;
2492 
2493  if (trans->txn_type != TXN_TYPE_UNCACHED)
2494  return trans->txn_type;
2495 
2496  trans->txn_type = TXN_TYPE_NONE;
2497  for (GList *n = xaccTransGetSplitList (trans); n; n = g_list_next (n))
2498  {
2499  Account *acc = xaccSplitGetAccount (GNC_SPLIT(n->data));
2500 
2501  if (!acc)
2502  continue;
2503 
2505  has_nonAPAR_split = TRUE;
2506  else if (trans->txn_type == TXN_TYPE_NONE)
2507  {
2508  GNCLot *lot = xaccSplitGetLot (GNC_SPLIT(n->data));
2509  GncInvoice *invoice = gncInvoiceGetInvoiceFromLot (lot);
2510  GncOwner owner;
2511 
2512  if (invoice && trans == gncInvoiceGetPostedTxn (invoice))
2513  trans->txn_type = TXN_TYPE_INVOICE;
2514  else if (invoice || gncOwnerGetOwnerFromLot (lot, &owner))
2515  trans->txn_type = TXN_TYPE_PAYMENT;
2516  }
2517  }
2518 
2519  if (!has_nonAPAR_split && (trans->txn_type == TXN_TYPE_PAYMENT))
2520  trans->txn_type = TXN_TYPE_LINK;
2521 
2522  return trans->txn_type;
2523 }
#define TXN_TYPE_INVOICE
Transaction is an invoice.
Definition: Transaction.h:126
GNCAccountType xaccAccountGetType(const Account *acc)
Returns the account&#39;s account type.
Definition: Account.cpp:3258
#define TXN_TYPE_NONE
No transaction type.
Definition: Transaction.h:125
gboolean gncOwnerGetOwnerFromLot(GNCLot *lot, GncOwner *owner)
Get the owner from the lot.
Definition: gncOwner.c:636
gboolean xaccAccountIsAPARType(GNCAccountType t)
Convenience function to check if the account is a valid business account type (meaning an Accounts Pa...
Definition: Account.cpp:4693
#define TXN_TYPE_LINK
Transaction is a link between (invoice and payment) lots.
Definition: Transaction.h:128
#define TXN_TYPE_PAYMENT
Transaction is a payment.
Definition: Transaction.h:127
GncInvoice * gncInvoiceGetInvoiceFromLot(GNCLot *lot)
Given a LOT, find and return the Invoice attached to the lot.
Definition: gncInvoice.c:1289
Account * xaccSplitGetAccount(const Split *split)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: gmock-Split.cpp:53
SplitList * xaccTransGetSplitList(const Transaction *trans)
The xaccTransGetSplitList() method returns a GList of the splits in a transaction.
GNCLot * xaccSplitGetLot(const Split *split)
Returns the pointer to the debited/credited Lot where this split belongs to, or NULL if it doesn&#39;t be...
Definition: Split.cpp:1915

◆ xaccTransGetVoidReason()

const char* xaccTransGetVoidReason ( const Transaction *  transaction)

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

Parameters
transactionThe transaction in question.
Returns
A pointer to the user supplied reason for voiding.

Definition at line 2759 of file Transaction.cpp.

2760 {
2761  g_return_val_if_fail (trans, nullptr);
2762 
2763  GValue v = G_VALUE_INIT;
2764  qof_instance_get_kvp (QOF_INSTANCE (trans), &v, 1, void_reason_str);
2765  const char *void_reason = G_VALUE_HOLDS_STRING (&v) ? g_value_get_string (&v) : nullptr;
2766  g_value_unset (&v);
2767 
2768  return void_reason;
2769 }
void qof_instance_get_kvp(QofInstance *, GValue *value, unsigned count,...)
Retrieves the contents of a KVP slot into a provided GValue.

◆ xaccTransGetVoidStatus()

gboolean xaccTransGetVoidStatus ( const Transaction *  transaction)

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

Parameters
transactionThe transaction in question.
Returns
TRUE if the transaction is void, FALSE otherwise. Also returns FALSE upon an error.

Definition at line 2752 of file Transaction.cpp.

2753 {
2754  const char *s = xaccTransGetVoidReason (trans);
2755  return (s && *s);
2756 }
const char * xaccTransGetVoidReason(const Transaction *trans)
Returns the user supplied textual reason why a transaction was voided.

◆ xaccTransGetVoidTime()

time64 xaccTransGetVoidTime ( const Transaction *  tr)

Returns the time that a transaction was voided.

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

Definition at line 2772 of file Transaction.cpp.

2773 {
2774  GValue v = G_VALUE_INIT;
2775  const char *s = nullptr;
2776  time64 void_time = 0;
2777 
2778  g_return_val_if_fail(tr, void_time);
2779  qof_instance_get_kvp (QOF_INSTANCE (tr), &v, 1, void_time_str);
2780  if (G_VALUE_HOLDS_STRING (&v))
2781  {
2782  s = g_value_get_string (&v);
2783  if (s)
2784  void_time = gnc_iso8601_to_time64_gmt (s);
2785  }
2786  g_value_unset (&v);
2787  return void_time;
2788 }
time64 gnc_iso8601_to_time64_gmt(const gchar *)
The gnc_iso8601_to_time64_gmt() routine converts an ISO-8601 style date/time string to time64...
void qof_instance_get_kvp(QofInstance *, GValue *value, unsigned count,...)
Retrieves the contents of a KVP slot into a provided GValue.
gint64 time64
Most systems that are currently maintained, including Microsoft Windows, BSD-derived Unixes and Linux...
Definition: gnc-date.h:87

◆ xaccTransIsBalanced()

gboolean xaccTransIsBalanced ( const Transaction *  trans)

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

Definition at line 1118 of file Transaction.cpp.

1119 {
1120  MonetaryList *imbal_list;
1121  gboolean result;
1122  gnc_numeric imbal = gnc_numeric_zero();
1123  gnc_numeric imbal_trading = gnc_numeric_zero();
1124 
1125  if (trans == nullptr) return FALSE;
1126 
1127  if (xaccTransUseTradingAccounts(trans))
1128  {
1129  /* Transaction is imbalanced if the value is imbalanced in either
1130  trading or non-trading splits. One can't be used to balance
1131  the other. */
1132  FOR_EACH_SPLIT(trans,
1133  {
1134  Account *acc = xaccSplitGetAccount(s);
1135  if (!acc || xaccAccountGetType(acc) != ACCT_TYPE_TRADING)
1136  {
1137  imbal = gnc_numeric_add(imbal, xaccSplitGetValue(s),
1139  }
1140  else
1141  {
1142  imbal_trading = gnc_numeric_add(imbal_trading, xaccSplitGetValue(s),
1144  }
1145  }
1146  );
1147  }
1148  else
1149  imbal = xaccTransGetImbalanceValue(trans);
1150 
1151  if (! gnc_numeric_zero_p(imbal) || ! gnc_numeric_zero_p(imbal_trading))
1152  return FALSE;
1153 
1154  if (!xaccTransUseTradingAccounts (trans))
1155  return TRUE;
1156 
1157  imbal_list = xaccTransGetImbalance(trans);
1158  result = imbal_list == nullptr;
1159  gnc_monetary_list_free(imbal_list);
1160  return result;
1161 }
gboolean xaccTransUseTradingAccounts(const Transaction *trans)
Determine whether this transaction should use commodity trading accounts.
GNCAccountType xaccAccountGetType(const Account *acc)
Returns the account&#39;s account type.
Definition: Account.cpp:3258
gnc_numeric gnc_numeric_add(gnc_numeric a, gnc_numeric b, gint64 denom, gint how)
Return a+b.
gboolean gnc_numeric_zero_p(gnc_numeric a)
Returns 1 if the given gnc_numeric is 0 (zero), else returns 0.
Use any denominator which gives an exactly correct ratio of numerator to denominator.
Definition: gnc-numeric.h:190
Account used to record multiple commodity transactions.
Definition: Account.h:155
gnc_numeric xaccTransGetImbalanceValue(const Transaction *trans)
The xaccTransGetImbalanceValue() method returns the total value of the transaction.
void gnc_monetary_list_free(MonetaryList *list)
Free a MonetaryList and all the monetaries it points to.
gnc_numeric xaccSplitGetValue(const Split *split)
Returns the value of this split in the transaction&#39;s commodity.
Definition: gmock-Split.cpp:84
Account * xaccSplitGetAccount(const Split *split)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: gmock-Split.cpp:53
MonetaryList * xaccTransGetImbalance(const Transaction *trans)
The xaccTransGetImbalance method returns a list giving the value of the transaction in each currency ...
#define GNC_DENOM_AUTO
Values that can be passed as the &#39;denom&#39; argument.
Definition: gnc-numeric.h:247

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

143 {
144  SCOPED_TRACE("");
145  auto mocktrans = gnc_mocktransaction(trans);
146  return mocktrans ? mocktrans->is_open() : FALSE;
147 }

◆ 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 2562 of file Transaction.cpp.

2563 {
2564  GDate *threshold_date;
2565  GDate trans_date;
2566  const QofBook *book = xaccTransGetBook (trans);
2567  gboolean result;
2568  g_assert(trans);
2569 
2570  if (!qof_book_uses_autoreadonly(book))
2571  {
2572  return FALSE;
2573  }
2574 
2575  if (xaccTransIsSXTemplate (trans))
2576  return FALSE;
2577 
2578  threshold_date = qof_book_get_autoreadonly_gdate(book);
2579  g_assert(threshold_date); // ok because we checked uses_autoreadonly before
2580  trans_date = xaccTransGetDatePostedGDate(trans);
2581 
2582 // g_warning("there is auto-read-only with days=%d, trans_date_day=%d, threshold_date_day=%d",
2583 // qof_book_get_num_days_autofreeze(book),
2584 // g_date_get_day(&trans_date),
2585 // g_date_get_day(threshold_date));
2586 
2587  if (g_date_compare(&trans_date, threshold_date) < 0)
2588  {
2589  //g_warning("we are auto-read-only");
2590  result = TRUE;
2591  }
2592  else
2593  {
2594  result = FALSE;
2595  }
2596  g_date_free(threshold_date);
2597  return result;
2598 }
GDate * qof_book_get_autoreadonly_gdate(const QofBook *book)
Returns the GDate that is the threshold for auto-read-only.
Definition: qofbook.cpp:988
#define xaccTransGetBook(X)
Definition: Transaction.h:802
gboolean qof_book_uses_autoreadonly(const QofBook *book)
Returns TRUE if the auto-read-only feature should be used, otherwise FALSE.
Definition: qofbook.cpp:962
GDate xaccTransGetDatePostedGDate(const Transaction *trans)
Retrieve the posted date of the transaction.

◆ 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 1018 of file Transaction.cpp.

1019 {
1020  QofCollection *col;
1021  if (!guid || !book) return nullptr;
1022  col = qof_book_get_collection (book, GNC_ID_TRANS);
1023  return (Transaction *) qof_collection_lookup_entity (col, guid);
1024 }
QofInstance * qof_collection_lookup_entity(const QofCollection *col, const GncGUID *guid)
Find the entity going only from its guid.
Definition: qofid.cpp:212
QofCollection * qof_book_get_collection(const QofBook *book, QofIdType entity_type)
Return The table of entities of the given type.
Definition: qofbook.cpp:521

◆ 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 1850 of file Transaction.cpp.

1851 {
1852  return xaccTransOrder_num_action (ta, nullptr, tb, nullptr);
1853 }
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.

◆ 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 1886 of file Transaction.cpp.

1888 {
1889  const char *da, *db;
1890  int retval;
1891 
1892  if ( ta && !tb ) return -1;
1893  if ( !ta && tb ) return +1;
1894  if ( !ta && !tb ) return 0;
1895 
1896  if (ta->date_posted != tb->date_posted)
1897  return (ta->date_posted > tb->date_posted) - (ta->date_posted < tb->date_posted);
1898 
1899  /* Always sort closing transactions after normal transactions */
1900  {
1901  gboolean ta_is_closing = xaccTransGetIsClosingTxn (ta);
1902  gboolean tb_is_closing = xaccTransGetIsClosingTxn (tb);
1903  if (ta_is_closing != tb_is_closing)
1904  return (ta_is_closing - tb_is_closing);
1905  }
1906 
1907  /* otherwise, sort on number string */
1908  if (actna && actnb) /* split action string, if not nullptr */
1909  {
1910  retval = order_by_int64_or_string (actna, actnb);
1911  }
1912  else /* else transaction num string */
1913  {
1914  retval = order_by_int64_or_string (ta->num, tb->num);
1915  }
1916  if (retval)
1917  return retval;
1918 
1919  if (ta->date_entered != tb->date_entered)
1920  return (ta->date_entered > tb->date_entered) - (ta->date_entered < tb->date_entered);
1921 
1922  /* otherwise, sort on description string */
1923  da = ta->description ? ta->description : "";
1924  db = tb->description ? tb->description : "";
1925  retval = g_utf8_collate (da, db);
1926  if (retval)
1927  return retval;
1928 
1929  /* else, sort on guid - keeps sort stable. */
1930  return qof_instance_guid_compare(ta, tb);
1931 }
gboolean xaccTransGetIsClosingTxn(const Transaction *trans)
Returns whether this transaction is a "closing transaction".
gint qof_instance_guid_compare(gconstpointer ptr1, gconstpointer ptr2)
Compare the GncGUID values of two instances.

◆ 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
transThe transaction whose price is recorded
sourceThe price priority level

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

158 {
159  g_return_if_fail(GNC_IS_MOCKTRANSACTION(trans));
160  ((MockTransaction*)trans)->recordPrice();
161 }

◆ 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 2464 of file Transaction.cpp.

2465 {
2466  return trans ? trans->date_entered : 0;
2467 }

◆ 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 2423 of file Transaction.cpp.

2424 {
2425  return trans ? trans->date_posted : 0;
2426 }

◆ 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
transactionThe transaction to create a reverse of.
Returns
a new transaction which reverses the given transaction

Definition at line 2817 of file Transaction.cpp.

2818 {
2819  Transaction *trans;
2820  GValue v = G_VALUE_INIT;
2821  g_return_val_if_fail(orig, nullptr);
2822 
2823  /* First edit, dirty, and commit orig to ensure that any trading
2824  * splits are correctly balanced.
2825  */
2826  xaccTransBeginEdit (orig);
2827  qof_instance_set_dirty (QOF_INSTANCE (orig));
2828  xaccTransCommitEdit (orig);
2829 
2830  trans = xaccTransClone(orig);
2831  g_return_val_if_fail (trans, nullptr);
2832  xaccTransBeginEdit(trans);
2833 
2834  /* Reverse the values on each split. Clear per-split info. */
2835  FOR_EACH_SPLIT(trans,
2836  {
2840  });
2841 
2842  /* Now update the original with a pointer to the new one */
2843  g_value_init (&v, GNC_TYPE_GUID);
2844  g_value_set_static_boxed (&v, xaccTransGetGUID(trans));
2845  qof_instance_set_kvp (QOF_INSTANCE (orig), &v, 1, TRANS_REVERSED_BY);
2846  g_value_unset (&v);
2847 
2848  /* Make sure the reverse transaction is not read-only */
2849  xaccTransClearReadOnly(trans);
2850 
2851  qof_instance_set_dirty(QOF_INSTANCE(trans));
2852  xaccTransCommitEdit(trans);
2853  return trans;
2854 }
void xaccSplitSetValue(Split *split, gnc_numeric val)
The xaccSplitSetValue() method sets the value of this split in the transaction&#39;s commodity.
Definition: gmock-Split.cpp:92
void qof_instance_set_kvp(QofInstance *, GValue const *value, unsigned count,...)
Sets a KVP slot to a value from a GValue.
gnc_numeric gnc_numeric_neg(gnc_numeric a)
Returns a newly created gnc_numeric that is the negative of the given gnc_numeric value...
void xaccSplitSetReconcile(Split *split, char recn)
Set the reconcile flag.
void xaccSplitSetAmount(Split *split, gnc_numeric amt)
The xaccSplitSetAmount() method sets the amount in the account&#39;s commodity that the split should have...
Definition: gmock-Split.cpp:77
Transaction * xaccTransClone(const Transaction *from)
The xaccTransClone() method will create a complete copy of an existing transaction.
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
#define xaccTransGetGUID(X)
Definition: Transaction.h:804
gnc_numeric xaccSplitGetValue(const Split *split)
Returns the value of this split in the transaction&#39;s commodity.
Definition: gmock-Split.cpp:84
#define NREC
not reconciled or cleared
Definition: Split.h:74
gnc_numeric xaccSplitGetAmount(const Split *split)
Returns the amount of the split in the account&#39;s commodity.
Definition: gmock-Split.cpp:69

◆ 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 1683 of file Transaction.cpp.

1684 {
1685  GList *node, *onode;
1686  QofBackend *be;
1687  Transaction *orig;
1688  GList *slist;
1689  int num_preexist, i;
1690 
1691 /* FIXME: This isn't quite the right way to handle nested edits --
1692  * there should be a stack of transaction states that are popped off
1693  * and restored at each level -- but it does prevent restoring to the
1694  * editlevel 0 state until one is returning to editlevel 0, and
1695  * thereby prevents a crash caused by trans->orig getting nullptred too
1696  * soon.
1697  */
1698  if (!qof_instance_get_editlevel (QOF_INSTANCE (trans))) return;
1699  if (qof_instance_get_editlevel (QOF_INSTANCE (trans)) > 1) {
1700  qof_instance_decrease_editlevel (QOF_INSTANCE (trans));
1701  return;
1702  }
1703 
1704  ENTER ("trans addr=%p\n", trans);
1705 
1706  check_open(trans);
1707 
1708  /* copy the original values back in. */
1709 
1710  orig = trans->orig;
1711  SWAP_STR(trans->num, orig->num);
1712  SWAP_STR(trans->description, orig->description);
1713  trans->date_entered = orig->date_entered;
1714  trans->date_posted = orig->date_posted;
1715  std::swap (trans->common_currency, orig->common_currency);
1716  qof_instance_swap_kvp (QOF_INSTANCE (trans), QOF_INSTANCE (orig));
1717 
1718  /* The splits at the front of trans->splits are exactly the same
1719  splits as in the original, but some of them may have changed, so
1720  we restore only those. */
1721 /* FIXME: Runs off the transaction's splits, so deleted splits are not
1722  * restored!
1723  */
1724  num_preexist = g_list_length(orig->splits);
1725  slist = g_list_copy(trans->splits);
1726  for (i = 0, node = slist, onode = orig->splits; node;
1727  i++, node = node->next, onode = onode ? onode->next : nullptr)
1728  {
1729  Split *s = GNC_SPLIT(node->data);
1730 
1731  if (!qof_instance_is_dirty(QOF_INSTANCE(s)))
1732  continue;
1733 
1734  if (i < num_preexist && onode)
1735  {
1736  Split *so = GNC_SPLIT(onode->data);
1737 
1738  xaccSplitRollbackEdit(s);
1739  SWAP_STR(s->action, so->action);
1740  SWAP_STR(s->memo, so->memo);
1741  qof_instance_copy_kvp (QOF_INSTANCE (s), QOF_INSTANCE (so));
1742  s->reconciled = so->reconciled;
1743  s->amount = so->amount;
1744  s->value = so->value;
1745  s->lot = so->lot;
1746  s->gains_split = so->gains_split;
1747  //SET_GAINS_A_VDIRTY(s);
1748  s->date_reconciled = so->date_reconciled;
1749  qof_instance_mark_clean(QOF_INSTANCE(s));
1750  }
1751  else
1752  {
1753  /* Potentially added splits */
1754  if (trans != xaccSplitGetParent(s))
1755  {
1756  trans->splits = g_list_remove(trans->splits, s);
1757  /* New split added, but then moved to another
1758  transaction */
1759  continue;
1760  }
1761  xaccSplitRollbackEdit(s);
1762  trans->splits = g_list_remove(trans->splits, s);
1763  g_assert(trans != xaccSplitGetParent(s));
1764  /* NB: our memory management policy here is that a new split
1765  added to the transaction which is then rolled-back still
1766  belongs to the engine. Specifically, it's freed by the
1767  transaction to which it was added. Don't add the Split to
1768  more than one transaction during the begin/commit block! */
1769  if (nullptr == xaccSplitGetParent(s))
1770  {
1771  xaccFreeSplit(s); // a newly malloc'd split
1772  }
1773  }
1774  }
1775  g_list_free(slist);
1776 
1777  // orig->splits may still have duped splits so free them
1778  g_list_free_full (orig->splits, (GDestroyNotify)xaccFreeSplit);
1779  orig->splits = nullptr;
1780 
1781  /* Now that the engine copy is back to its original version,
1782  * get the backend to fix it in the database */
1786  if (qof_backend_can_rollback (be))
1787  {
1788  QofBackendError errcode;
1789 
1790  /* clear errors */
1791  do
1792  {
1793  errcode = qof_backend_get_error (be);
1794  }
1795  while (ERR_BACKEND_NO_ERR != errcode);
1796 
1797  qof_backend_rollback_instance (be, &(trans->inst));
1798 
1799  errcode = qof_backend_get_error (be);
1800  if (ERR_BACKEND_MOD_DESTROY == errcode)
1801  {
1802  /* The backend is asking us to delete this transaction.
1803  * This typically happens because another (remote) user
1804  * has deleted this transaction, and we haven't found
1805  * out about it until this user tried to edit it.
1806  */
1807  xaccTransDestroy (trans);
1808  do_destroy (QOF_INSTANCE(trans));
1809 
1810  /* push error back onto the stack */
1811  qof_backend_set_error (be, errcode);
1812  LEAVE ("deleted trans addr=%p\n", trans);
1813  return;
1814  }
1815  if (ERR_BACKEND_NO_ERR != errcode)
1816  {
1817  PERR ("Rollback Failed. Ouch!");
1818  /* push error back onto the stack */
1819  qof_backend_set_error (be, errcode);
1820  }
1821  }
1822 
1824  xaccTransWriteLog (trans, 'R');
1825 
1826  xaccFreeTransaction (trans->orig);
1827 
1828  trans->orig = nullptr;
1829  qof_instance_set_destroying(trans, FALSE);
1830 
1831  /* Put back to zero. */
1832  qof_instance_decrease_editlevel(trans);
1833  /* FIXME: The register code seems to depend on the engine to
1834  generate an event during rollback, even though the state is just
1835  reverting to what it was. */
1836  gen_event_trans (trans);
1837 
1838  LEAVE ("trans addr=%p\n", trans);
1839 }
commit of object update failed because another user has deleted the object
Definition: qofbackend.h:77
#define qof_instance_is_dirty
Return value of is_dirty flag.
Definition: qofinstance.h:166
QofBook * qof_instance_get_book(gconstpointer inst)
Return the book pointer.
QofBackendError
The errors that can be reported to the GUI & other front-end users.
Definition: qofbackend.h:57
void xaccTransWriteLog(Transaction *trans, char flag)
Definition: TransLog.cpp:223
void qof_backend_set_error(QofBackend *qof_be, QofBackendError err)
Set the error on the specified QofBackend.
Transaction * xaccSplitGetParent(const Split *split)
Returns the parent transaction of the split.
#define PERR(format, args...)
Log a serious error.
Definition: qoflog.h:244
#define ENTER(format, args...)
Print a function entry debugging message.
Definition: qoflog.h:272
QofBackendError qof_backend_get_error(QofBackend *qof_be)
Get the last backend error.
void xaccTransDestroy(Transaction *trans)
Destroys a transaction.
gboolean qof_book_is_readonly(const QofBook *book)
Return whether the book is read only.
Definition: qofbook.cpp:497
#define LEAVE(format, args...)
Print a function exit debugging message.
Definition: qoflog.h:282
QofBackend * qof_book_get_backend(const QofBook *book)
Retrieve the backend used by this book.
Definition: qofbook.cpp:440

◆ 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 2915 of file Transaction.cpp.

2916 {
2917  SplitList *node;
2918 
2919  ENTER("(trans=%p)", trans);
2920  /* Lock down posted date, its to be synced to the posted date
2921  * for the source of the cap gains. */
2922  xaccTransScrubGainsDate(trans);
2923 
2924  /* Fix up the split amount */
2925 restart:
2926  for (node = trans->splits; node; node = node->next)
2927  {
2928  Split *s = GNC_SPLIT(node->data);
2929 
2930  if (!xaccTransStillHasSplit(trans, s)) continue;
2931 
2932  xaccSplitDetermineGainStatus(s);
2933  if (s->gains & GAINS_STATUS_ADIRTY)
2934  {
2935  gboolean altered = FALSE;
2936  s->gains &= ~GAINS_STATUS_ADIRTY;
2937  if (s->lot)
2938  altered = xaccScrubLot(s->lot);
2939  else
2940  altered = xaccSplitAssign(s);
2941  if (altered) goto restart;
2942  }
2943  }
2944 
2945  /* Fix up gains split value */
2946  FOR_EACH_SPLIT(trans,
2947  if ((s->gains & GAINS_STATUS_VDIRTY) ||
2948  (s->gains_split &&
2949  (s->gains_split->gains & GAINS_STATUS_VDIRTY)))
2950  xaccSplitComputeCapGains(s, gain_acc);
2951  );
2952 
2953  LEAVE("(trans=%p)", trans);
2954 }
void xaccSplitComputeCapGains(Split *split, Account *gain_acc)
The xaccSplitComputeCapGains() routine computes the cap gains or losses for the indicated split...
Definition: cap-gains.cpp:528
#define ENTER(format, args...)
Print a function entry debugging message.
Definition: qoflog.h:272
GList SplitList
GList of Split.
Definition: gnc-engine.h:207
gboolean xaccSplitAssign(Split *split)
The`xaccSplitAssign() routine will take the indicated split and, if it doesn&#39;t already belong to a lo...
Definition: cap-gains.cpp:428
#define LEAVE(format, args...)
Print a function exit debugging message.
Definition: qoflog.h:282
gboolean xaccScrubLot(GNCLot *lot)
The xaccScrubLot() routine makes sure that the indicated lot is self-consistent and properly balanced...
Definition: Scrub3.cpp:85

◆ 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
transThe transaction to change
currThe new currency to set.

Definition at line 1401 of file Transaction.cpp.

1402 {
1403  gnc_commodity *old_curr = trans->common_currency;
1404  if (!trans || !curr || trans->common_currency == curr) return;
1405  xaccTransBeginEdit(trans);
1406 
1407  trans->common_currency = curr;
1408  if (old_curr != nullptr && trans->splits != nullptr)
1409  {
1410  gnc_numeric rate = find_new_rate(trans, curr);
1411  if (!gnc_numeric_zero_p (rate))
1412  {
1413  FOR_EACH_SPLIT(trans, split_set_new_value(s, curr, old_curr, rate));
1414  }
1415  else
1416  {
1417  FOR_EACH_SPLIT(trans, xaccSplitSetValue(s, xaccSplitGetValue(s)));
1418  }
1419  }
1420 
1421  qof_instance_set_dirty(QOF_INSTANCE(trans));
1422  mark_trans(trans); /* Dirty balance of every account in trans */
1423  xaccTransCommitEdit(trans);
1424 }
void xaccSplitSetValue(Split *split, gnc_numeric val)
The xaccSplitSetValue() method sets the value of this split in the transaction&#39;s commodity.
Definition: gmock-Split.cpp:92
gboolean gnc_numeric_zero_p(gnc_numeric a)
Returns 1 if the given gnc_numeric is 0 (zero), else returns 0.
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
gnc_numeric xaccSplitGetValue(const Split *split)
Returns the value of this split in the transaction&#39;s commodity.
Definition: gmock-Split.cpp:84

◆ 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 2014 of file Transaction.cpp.

2015 {
2016  GDate *date;
2017  if (!trans) return;
2018  date = g_date_new_dmy(day, static_cast<GDateMonth>(mon), year);
2019  if (!g_date_valid(date))
2020  {
2021  PWARN("Attempted to set invalid date %d-%d-%d; set today's date instead.",
2022  year, mon, day);
2023  g_free(date);
2024  date = gnc_g_date_new_today();
2025  }
2026  xaccTransSetDatePostedGDate(trans, *date);
2027  g_free(date);
2028 }
void xaccTransSetDatePostedGDate(Transaction *trans, GDate date)
This method modifies posted date of the transaction, specified by a GDate.
#define PWARN(format, args...)
Log a warning.
Definition: qoflog.h:250
GDate * gnc_g_date_new_today()
Returns a newly allocated date of the current clock time, taken from time(2).
Definition: gnc-date.cpp:1224

◆ 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 2007 of file Transaction.cpp.

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

◆ 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 1988 of file Transaction.cpp.

1989 {
1990  GValue v = G_VALUE_INIT;
1991  if (!trans) return;
1992 
1993  /* We additionally save this date into a kvp frame to ensure in
1994  * the future a date which was set as *date* (without time) can
1995  * clearly be distinguished from the time64. */
1996  g_value_init (&v, G_TYPE_DATE);
1997  g_value_set_static_boxed (&v, &date);
1998  qof_instance_set_kvp (QOF_INSTANCE(trans), &v, 1, TRANS_DATE_POSTED);
1999  g_value_unset (&v);
2000  /* mark dirty and commit handled by SetDateInternal */
2001  xaccTransSetDateInternal(trans, &trans->date_posted,
2002  gdate_to_time64(date));
2003  set_gains_date_dirty (trans);
2004 }
void qof_instance_set_kvp(QofInstance *, GValue const *value, unsigned count,...)
Sets a KVP slot to a value from a GValue.
time64 gdate_to_time64(GDate d)
Turns a GDate into a time64, returning the first second of the day.
Definition: gnc-date.cpp:1252

◆ 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 1972 of file Transaction.cpp.

1973 {
1974  if (!trans) return;
1975  xaccTransSetDateInternal(trans, &trans->date_posted, secs);
1976  set_gains_date_dirty(trans);
1977 }

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

82 {
83  ASSERT_TRUE(GNC_IS_MOCKTRANSACTION(trans));
84  gnc_mocktransaction(trans)->set_date_posted_secs_normalized(time);
85 }

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

112 {
113  ASSERT_TRUE(GNC_IS_MOCKTRANSACTION(trans));
114  gnc_mocktransaction(trans)->set_notes(notes);
115 }

◆ 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 2077 of file Transaction.cpp.

2078 {
2079  if (trans && reason)
2080  {
2081  GValue v = G_VALUE_INIT;
2082  g_value_init (&v, G_TYPE_STRING);
2083  g_value_set_static_string (&v, reason);
2084  xaccTransBeginEdit(trans);
2085  qof_instance_set_kvp (QOF_INSTANCE (trans), &v, 1, TRANS_READ_ONLY_REASON);
2086  qof_instance_set_dirty(QOF_INSTANCE(trans));
2087  g_value_unset (&v);
2088  xaccTransCommitEdit(trans);
2089  }
2090 }
void qof_instance_set_kvp(QofInstance *, GValue const *value, unsigned count,...)
Sets a KVP slot to a value from a GValue.
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...

◆ 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 2045 of file Transaction.cpp.

2046 {
2047  char s[2] = {type, '\0'};
2048  GValue v = G_VALUE_INIT;
2049  g_return_if_fail(trans);
2050  g_value_init (&v, G_TYPE_STRING);
2051  qof_instance_get_kvp (QOF_INSTANCE (trans), &v, 1, TRANS_TXN_TYPE_KVP);
2052  if (!g_strcmp0 (s, g_value_get_string (&v)))
2053  {
2054  g_value_unset (&v);
2055  return;
2056  }
2057  g_value_set_static_string (&v, s);
2058  xaccTransBeginEdit(trans);
2059  qof_instance_set_kvp (QOF_INSTANCE (trans), &v, 1, TRANS_TXN_TYPE_KVP);
2060  qof_instance_set_dirty(QOF_INSTANCE(trans));
2061  g_value_unset (&v);
2062  xaccTransCommitEdit(trans);
2063 }
void qof_instance_set_kvp(QofInstance *, GValue const *value, unsigned count,...)
Sets a KVP slot to a value from a GValue.
void qof_instance_get_kvp(QofInstance *, GValue *value, unsigned count,...)
Retrieves the contents of a KVP slot into a provided GValue.
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...

◆ 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
transactionThe transaction to restore from voided state.

Definition at line 2791 of file Transaction.cpp.

2792 {
2793  GValue v = G_VALUE_INIT;
2794  const char *s = nullptr;
2795  g_return_if_fail(trans);
2796 
2797  s = xaccTransGetVoidReason (trans);
2798  if (s == nullptr) return; /* Transaction isn't voided. Bail. */
2799  xaccTransBeginEdit(trans);
2800 
2801  qof_instance_get_kvp (QOF_INSTANCE (trans), &v, 1, void_former_notes_str);
2802  if (G_VALUE_HOLDS_STRING (&v))
2803  qof_instance_set_kvp (QOF_INSTANCE (trans), &v, 1, trans_notes_str);
2804  qof_instance_set_kvp (QOF_INSTANCE (trans), nullptr, 1, void_former_notes_str);
2805  qof_instance_set_kvp (QOF_INSTANCE (trans), nullptr, 1, void_reason_str);
2806  qof_instance_set_kvp (QOF_INSTANCE (trans), nullptr, 1, void_time_str);
2807  g_value_unset (&v);
2808 
2809  FOR_EACH_SPLIT(trans, xaccSplitUnvoid(s));
2810 
2811  /* Dirtying taken care of by ClearReadOnly */
2812  xaccTransClearReadOnly(trans);
2813  xaccTransCommitEdit(trans);
2814 }
void qof_instance_set_kvp(QofInstance *, GValue const *value, unsigned count,...)
Sets a KVP slot to a value from a GValue.
const char * xaccTransGetVoidReason(const Transaction *trans)
Returns the user supplied textual reason why a transaction was voided.
void qof_instance_get_kvp(QofInstance *, GValue *value, unsigned count,...)
Retrieves the contents of a KVP slot into a provided GValue.
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...

◆ 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
transactionThe transaction to void.
reasonThe textual reason why this transaction is being voided.

Definition at line 2712 of file Transaction.cpp.

2713 {
2714  GValue v = G_VALUE_INIT;
2715  char iso8601_str[ISO_DATELENGTH + 1] = "";
2716 
2717  g_return_if_fail(trans && reason);
2718 
2719  /* Prevent voiding transactions that are already marked
2720  * read only, for example generated by the business features.
2721  */
2722  if (xaccTransGetReadOnly (trans))
2723  {
2724  PWARN ("Refusing to void a read-only transaction!");
2725  return;
2726  }
2727  xaccTransBeginEdit(trans);
2728  qof_instance_get_kvp (QOF_INSTANCE (trans), &v, 1, trans_notes_str);
2729  if (G_VALUE_HOLDS_STRING (&v))
2730  qof_instance_set_kvp (QOF_INSTANCE (trans), &v, 1, void_former_notes_str);
2731  else
2732  g_value_init (&v, G_TYPE_STRING);
2733 
2734  g_value_set_static_string (&v, _("Voided transaction"));
2735  qof_instance_set_kvp (QOF_INSTANCE (trans), &v, 1, trans_notes_str);
2736  g_value_set_static_string (&v, reason);
2737  qof_instance_set_kvp (QOF_INSTANCE (trans), &v, 1, void_reason_str);
2738 
2739  gnc_time64_to_iso8601_buff (gnc_time(nullptr), iso8601_str);
2740  g_value_set_static_string (&v, iso8601_str);
2741  qof_instance_set_kvp (QOF_INSTANCE (trans), &v, 1, void_time_str);
2742  g_value_unset (&v);
2743 
2744  FOR_EACH_SPLIT(trans, xaccSplitVoid(s));
2745 
2746  /* Dirtying taken care of by SetReadOnly */
2747  xaccTransSetReadOnly(trans, _("Transaction Voided"));
2748  xaccTransCommitEdit(trans);
2749 }
void qof_instance_set_kvp(QofInstance *, GValue const *value, unsigned count,...)
Sets a KVP slot to a value from a GValue.
const char * xaccTransGetReadOnly(Transaction *trans)
Returns a non-NULL value if this Transaction was marked as read-only with some specific "reason" text...
void qof_instance_get_kvp(QofInstance *, GValue *value, unsigned count,...)
Retrieves the contents of a KVP slot into a provided GValue.
#define PWARN(format, args...)
Log a warning.
Definition: qoflog.h:250
void xaccTransSetReadOnly(Transaction *trans, const char *reason)
Set the transaction to be ReadOnly by setting a non-NULL value as "reason".
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
time64 gnc_time(time64 *tbuf)
get the current time
Definition: gnc-date.cpp:261
char * gnc_time64_to_iso8601_buff(time64 time, char *buff)
The gnc_time64_to_iso8601_buff() routine takes the input UTC time64 value and prints it as an ISO-860...
Definition: gnc-date.cpp:1139