GnuCash  4.8a-86-g9eaa3eb23
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_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. More...
 
char xaccTransGetTxnType (const Transaction *trans)
 Returns the Transaction Type. 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".
 
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 554 of file Split.h.

◆ xaccSplitReturnGUID

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

Definition at line 556 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 362 of file Transaction.h.

◆ xaccTransGetBook

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

Definition at line 783 of file Transaction.h.

◆ xaccTransGetGUID

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

Definition at line 785 of file Transaction.h.

◆ xaccTransReturnGUID

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

Definition at line 787 of file Transaction.h.

Function Documentation

◆ gnc_book_count_transactions()

guint gnc_book_count_transactions ( QofBook *  book)
Warning
XXX FIXME gnc_book_count_transactions is a utility function, probably needs to be moved to a utility file somewhere.

Definition at line 2744 of file Transaction.c.

2745 {
2746  guint count = 0;
2747  xaccAccountTreeForEachTransaction(gnc_book_get_root_account(book),
2748  counter_thunk, (void*)&count);
2749  return count;
2750 }
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 510 of file Transaction.c.

511 {
512  Transaction *trans;
513 
514  g_return_val_if_fail (book, NULL);
515 
516  trans = g_object_new(GNC_TYPE_TRANSACTION, NULL);
517  xaccInitTransaction (trans, book);
518  qof_event_gen (&trans->inst, QOF_EVENT_CREATE, NULL);
519 
520  return trans;
521 }
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 2020 of file Split.c.

2022 {
2023  const GncGUID* guid;
2024 
2025  g_return_if_fail (split != NULL);
2026  g_return_if_fail (other_split != NULL);
2027 
2028  guid = qof_instance_get_guid (QOF_INSTANCE (other_split));
2029  xaccTransBeginEdit (split->parent);
2030  qof_instance_kvp_add_guid (QOF_INSTANCE (split), "lot-split",
2031  gnc_time(NULL), "peer_guid", guid_copy(guid));
2032  mark_split (split);
2033  qof_instance_set_dirty (QOF_INSTANCE (split));
2034  xaccTransCommitEdit (split->parent);
2035 }
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:121
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 local time
Definition: gnc-date.cpp:273
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 1673 of file Split.c.

1674 {
1675  Account *aa, *ab;
1676  if (!sa && !sb) return 0;
1677  if (!sa) return -1;
1678  if (!sb) return 1;
1679 
1680  aa = sa->acc;
1681  ab = sb->acc;
1682 
1683  return g_strcmp0(xaccAccountGetCode(aa), xaccAccountGetCode(ab));
1684 }
const char * xaccAccountGetCode(const Account *acc)
Get the account's accounting code.
Definition: Account.cpp:3313

◆ xaccSplitCompareAccountFullNames()

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

Compare two splits by full name of account.

Returns similar to strcmp.

Definition at line 1652 of file Split.c.

1653 {
1654  Account *aa, *ab;
1655  char *full_a, *full_b;
1656  int retval;
1657  if (!sa && !sb) return 0;
1658  if (!sa) return -1;
1659  if (!sb) return 1;
1660 
1661  aa = sa->acc;
1662  ab = sb->acc;
1663  full_a = gnc_account_get_full_name(aa);
1664  full_b = gnc_account_get_full_name(ab);
1665  retval = g_utf8_collate(full_a, full_b);
1666  g_free(full_a);
1667  g_free(full_b);
1668  return retval;
1669 }
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:3265

◆ 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 1708 of file Split.c.

1709 {
1710  const char *ca, *cb;
1711  if (!sa && !sb) return 0;
1712  if (!sa) return -1;
1713  if (!sb) return 1;
1714 
1715  ca = xaccSplitGetCorrAccountCode(sa);
1716  cb = xaccSplitGetCorrAccountCode(sb);
1717  return g_strcmp0(ca, cb);
1718 }
const char * xaccSplitGetCorrAccountCode(const Split *sa)
document me
Definition: Split.c:1635

◆ 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 1687 of file Split.c.

1688 {
1689  char *ca, *cb;
1690  int retval;
1691  if (!sa && !sb) return 0;
1692  if (!sa) return -1;
1693  if (!sb) return 1;
1694 
1695  /* doesn't matter what separator we use
1696  * as long as they are the same
1697  */
1698 
1701  retval = g_strcmp0(ca, cb);
1702  g_free(ca);
1703  g_free(cb);
1704  return retval;
1705 }
char * xaccSplitGetCorrAccountFullName(const Split *sa)
These functions take a split, get the corresponding split on the "other side" of the transaction...
Definition: Split.c:1619

◆ 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 639 of file Split.c.

640 {
641  if (!from_split || !to_split) return;
642  xaccTransBeginEdit (to_split->parent);
643 
644  xaccSplitSetMemo(to_split, xaccSplitGetMemo(from_split));
645  xaccSplitSetAction(to_split, xaccSplitGetAction(from_split));
646  xaccSplitSetAmount(to_split, xaccSplitGetAmount(from_split));
647  xaccSplitSetValue(to_split, xaccSplitGetValue(from_split));
648  /* Setting the account is okay here because, even though the from
649  split might not really belong to the account it claims to,
650  setting the account won't cause any event involving from. */
651  xaccSplitSetAccount(to_split, xaccSplitGetAccount(from_split));
652  /* N.B. Don't set parent. */
653 
654  qof_instance_set_dirty(QOF_INSTANCE(to_split));
655  xaccTransCommitEdit(to_split->parent);
656 }
void xaccSplitSetValue(Split *s, gnc_numeric amt)
The xaccSplitSetValue() method sets the value of this split in the transaction's commodity.
Definition: Split.c:1266
void xaccSplitSetAction(Split *split, const char *actn)
The Action is an arbitrary user-assigned string.
Definition: Split.c:1747
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.c:1230
void xaccSplitSetMemo(Split *split, const char *memo)
The memo is an arbitrary string associated with a split.
Definition: Split.c:1728
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.c:1921
Account * xaccSplitGetAccount(const Split *s)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: Split.c:936
const char * xaccSplitGetMemo(const Split *split)
Returns the memo string.
Definition: Split.c:1896
const char * xaccSplitGetAction(const Split *split)
Returns the action string.
Definition: Split.c:1902
gnc_numeric xaccSplitGetAmount(const Split *split)
Returns the amount of the split in the account's commodity.
Definition: Split.c:1915

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

If the deletion of the split leaves the transaction with no splits, then the transaction will be marked for deletion. (It will not be deleted until the xaccTransCommitEdit() routine is called.)

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

Definition at line 1470 of file Split.c.

1471 {
1472  Account *acc;
1473  Transaction *trans;
1474  GncEventData ed;
1475 
1476  if (!split) return TRUE;
1477 
1478  acc = split->acc;
1479  trans = split->parent;
1480  if (acc && !qof_instance_get_destroying(acc)
1481  && !qof_instance_get_destroying(trans)
1482  && xaccTransGetReadOnly(trans))
1483  return FALSE;
1484 
1485  xaccTransBeginEdit(trans);
1486  ed.node = split;
1487  ed.idx = xaccTransGetSplitIndex(trans, split);
1488  qof_instance_set_dirty(QOF_INSTANCE(split));
1489  qof_instance_set_destroying(split, TRUE);
1490  qof_event_gen(&trans->inst, GNC_EVENT_ITEM_REMOVED, &ed);
1491  xaccTransCommitEdit(trans);
1492 
1493  return TRUE;
1494 }
const char * xaccTransGetReadOnly(Transaction *trans)
Returns a non-NULL value if this Transaction was marked as read-only with some specific "reason" text...
Definition: Transaction.c:2567
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()
Definition: Transaction.c:2303
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 769 of file Split.c.

773 {
774  gboolean same_book;
775 
776  if (!sa && !sb) return TRUE; /* Arguable. FALSE is better, methinks */
777 
778  if (!sa || !sb)
779  {
780  PINFO ("one is NULL");
781  return FALSE;
782  }
783 
784  if (sa == sb) return TRUE;
785 
786  same_book = qof_instance_get_book(QOF_INSTANCE(sa)) == qof_instance_get_book(QOF_INSTANCE(sb));
787 
788  if (check_guids)
789  {
790  if (qof_instance_guid_compare(sa, sb) != 0)
791  {
792  PINFO ("GUIDs differ");
793  return FALSE;
794  }
795  }
796 
797  /* If the same book, since these strings are cached we can just use pointer equality */
798  if ((same_book && sa->memo != sb->memo) || (!same_book && g_strcmp0(sa->memo, sb->memo) != 0))
799  {
800  PINFO ("memos differ: (%p)%s vs (%p)%s",
801  sa->memo, sa->memo, sb->memo, sb->memo);
802  return FALSE;
803  }
804 
805  if ((same_book && sa->action != sb->action) || (!same_book && g_strcmp0(sa->action, sb->action) != 0))
806  {
807  PINFO ("actions differ: %s vs %s", sa->action, sb->action);
808  return FALSE;
809  }
810 
811  if (qof_instance_compare_kvp (QOF_INSTANCE (sa), QOF_INSTANCE (sb)) != 0)
812  {
813  char *frame_a;
814  char *frame_b;
815 
816  frame_a = qof_instance_kvp_as_string (QOF_INSTANCE (sa));
817  frame_b = qof_instance_kvp_as_string (QOF_INSTANCE (sb));
818 
819  PINFO ("kvp frames differ:\n%s\n\nvs\n\n%s", frame_a, frame_b);
820 
821  g_free (frame_a);
822  g_free (frame_b);
823 
824  return FALSE;
825  }
826 
827  if (sa->reconciled != sb->reconciled)
828  {
829  PINFO ("reconcile flags differ: %c vs %c", sa->reconciled, sb->reconciled);
830  return FALSE;
831  }
832 
833  if (sa->date_reconciled != sb->date_reconciled)
834  {
835  PINFO ("reconciled date differs");
836  return FALSE;
837  }
838 
840  {
841  char *str_a;
842  char *str_b;
843 
846 
847  PINFO ("amounts differ: %s vs %s", str_a, str_b);
848 
849  g_free (str_a);
850  g_free (str_b);
851 
852  return FALSE;
853  }
854 
856  {
857  char *str_a;
858  char *str_b;
859 
862 
863  PINFO ("values differ: %s vs %s", str_a, str_b);
864 
865  g_free (str_a);
866  g_free (str_b);
867 
868  return FALSE;
869  }
870 
871  if (check_balances)
872  {
873  if (!xaccSplitEqualCheckBal ("", sa->balance, sb->balance))
874  return FALSE;
875  if (!xaccSplitEqualCheckBal ("cleared ", sa->cleared_balance,
876  sb->cleared_balance))
877  return FALSE;
878  if (!xaccSplitEqualCheckBal ("reconciled ", sa->reconciled_balance,
879  sb->reconciled_balance))
880  return FALSE;
881  if (!xaccSplitEqualCheckBal ("noclosing ", sa->noclosing_balance,
882  sb->noclosing_balance))
883  return FALSE;
884  }
885 
886  if (!xaccTransEqual(sa->parent, sb->parent, check_guids, check_txn_splits,
887  check_balances, FALSE))
888  {
889  PINFO ("transactions differ");
890  return FALSE;
891  }
892 
893  return TRUE;
894 }
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.
Definition: Transaction.c:874
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.c:1921
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.c:1915

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

130 {
131  SCOPED_TRACE("");
132  auto mocksplit = gnc_mocksplit(split);
133  return mocksplit ? mocksplit->get_action() : "";
134 }

◆ 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 1295 of file Split.c.

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

◆ 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 1374 of file Split.c.

1375 {
1376  if (!s || !s->acc || !s->parent) return gnc_numeric_zero();
1377 
1378  /* be more precise -- the value depends on the currency we want it
1379  * expressed in. */
1380  if (gnc_commodity_equiv(xaccTransGetCurrency(s->parent), base_currency))
1381  return xaccSplitGetValue(s);
1382  if (gnc_commodity_equiv(xaccAccountGetCommodity(s->acc), base_currency))
1383  return xaccSplitGetAmount(s);
1384 
1385  PERR ("inappropriate base currency %s "
1386  "given split currency=%s and commodity=%s\n",
1387  gnc_commodity_get_printname(base_currency),
1390  return gnc_numeric_zero();
1391 }
#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.c:1921
gnc_commodity * xaccAccountGetCommodity(const Account *acc)
Get the account's commodity.
Definition: Account.cpp:3405
gnc_commodity * xaccTransGetCurrency(const Transaction *trans)
Returns the valuation commodity of this transaction.
Definition: Transaction.c:1366
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.c:1915

◆ 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 1307 of file Split.c.

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

◆ 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 1619 of file Split.c.

1620 {
1621  static const char *split_const = NULL;
1622  const Split *other_split;
1623 
1624  if (!get_corr_account_split(sa, &other_split))
1625  {
1626  if (!split_const)
1627  split_const = _("-- Split Transaction --");
1628 
1629  return g_strdup(split_const);
1630  }
1631  return gnc_account_get_full_name(other_split->acc);
1632 }
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:3265

◆ xaccSplitGetDateReconciled()

time64 xaccSplitGetDateReconciled ( const Split *  split)

Retrieve the date when the Split was reconciled.

Definition at line 1820 of file Split.c.

1821 {
1822  return split ? split->date_reconciled : 0;
1823 }

◆ 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 1881 of file Split.c.

1882 {
1883  return split ? split->lot : NULL;
1884 }

◆ 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 1301 of file Split.c.

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

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

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

◆ xaccSplitGetParent()

Transaction* xaccSplitGetParent ( const Split *  split)

Returns the parent transaction of the split.

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

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

◆ xaccSplitGetReconcile()

char xaccSplitGetReconcile ( const Split *  split)

Returns the value of the reconcile flag.

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

108 {
109  SCOPED_TRACE("");
110  auto mocksplit = gnc_mocksplit(split);
111  return mocksplit ? mocksplit->get_reconcile() : VREC;
112 }
#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 1313 of file Split.c.

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

◆ 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 1927 of file Split.c.

1928 {
1929  gnc_numeric amt, val, price;
1930  if (!split) return gnc_numeric_create(1, 1);
1931 
1932 
1933  /* if amount == 0 and value == 0, then return 1.
1934  * if amount == 0 and value != 0 then return 0.
1935  * otherwise return value/amount
1936  */
1937 
1938  amt = xaccSplitGetAmount(split);
1939  val = xaccSplitGetValue(split);
1940  if (gnc_numeric_zero_p(amt))
1941  {
1942  if (gnc_numeric_zero_p(val))
1943  return gnc_numeric_create(1, 1);
1944  return gnc_numeric_create(0, 1);
1945  }
1946  price = gnc_numeric_div(val, amt,
1949 
1950  /* During random checks we can get some very weird prices. Let's
1951  * handle some overflow and other error conditions by returning
1952  * zero. But still print an error to let us know it happened.
1953  */
1954  if (gnc_numeric_check(price))
1955  {
1956  PERR("Computing share price failed (%d): [ %" G_GINT64_FORMAT " / %"
1957  G_GINT64_FORMAT " ] / [ %" G_GINT64_FORMAT " / %" G_GINT64_FORMAT " ]",
1958  gnc_numeric_check(price), val.num, val.denom, amt.num, amt.denom);
1959  return gnc_numeric_create(0, 1);
1960  }
1961 
1962  return price;
1963 }
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
Round to the nearest integer, rounding away from zero when there are two equidistant nearest integers...
Definition: gnc-numeric.h:166
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.c:1921
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:246
gnc_numeric xaccSplitGetAmount(const Split *split)
Returns the amount of the split in the account's commodity.
Definition: Split.c:1915

◆ 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 1975 of file Split.c.

1976 {
1977  if (!s) return NULL;
1978  if (s->split_type == is_unset)
1979  {
1980  GValue v = G_VALUE_INIT;
1981  Split *split = (Split*) s;
1982  const char* type;
1983  qof_instance_get_kvp (QOF_INSTANCE (s), &v, 1, "split-type");
1984  type = G_VALUE_HOLDS_STRING (&v) ? g_value_get_string (&v) : NULL;
1985  if (!type || !g_strcmp0 (type, split_type_normal))
1986  split->split_type = (char*) split_type_normal;
1987  else if (!g_strcmp0 (type, split_type_stock_split))
1988  split->split_type = (char*) split_type_stock_split;
1989  else
1990  {
1991  PERR ("unexpected split-type %s, reset to normal.", type);
1992  split->split_type = split_type_normal;
1993  }
1994  g_value_unset (&v);
1995  }
1996  return s->split_type;
1997 }
#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 2044 of file Split.c.

2045 {
2046  const GncGUID* guid;
2047 
2048  g_return_val_if_fail (split != NULL, FALSE);
2049  g_return_val_if_fail (other_split != NULL, FALSE);
2050 
2051  guid = qof_instance_get_guid (QOF_INSTANCE (other_split));
2052  return qof_instance_kvp_has_guid (QOF_INSTANCE (split), "lot-split",
2053  "peer_guid", guid);
2054 }
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 1072 of file Split.c.

1073 {
1074  QofCollection *col;
1075  if (!guid || !book) return NULL;
1076  col = qof_book_get_collection (book, GNC_ID_SPLIT);
1077  return (Split *) qof_collection_lookup_entity (col, guid);
1078 }
QofInstance * qof_collection_lookup_entity(const QofCollection *col, const GncGUID *guid)
Find the entity going only from its guid.
Definition: qofid.cpp:215
QofCollection * qof_book_get_collection(const QofBook *book, QofIdType entity_type)
Return The table of entities of the given type.
Definition: qofbook.cpp:604

◆ 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 2002 of file Split.c.

2003 {
2004  GValue v = G_VALUE_INIT;
2005  xaccTransBeginEdit (s->parent);
2006 
2007  s->value = gnc_numeric_zero();
2008  g_value_init (&v, G_TYPE_STRING);
2009  g_value_set_static_string (&v, split_type_stock_split);
2010  s->split_type = split_type_stock_split;
2011  qof_instance_set_kvp (QOF_INSTANCE (s), &v, 1, "split-type");
2012  SET_GAINS_VDIRTY(s);
2013  mark_split(s);
2014  qof_instance_set_dirty(QOF_INSTANCE(s));
2015  xaccTransCommitEdit(s->parent);
2016  g_value_unset (&v);
2017 }
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 2074 of file Split.c.

2075 {
2076  xaccTransBeginEdit (split->parent);
2077  qof_instance_kvp_merge_guids (QOF_INSTANCE (split),
2078  QOF_INSTANCE (other_split), "lot-split");
2079  mark_split (split);
2080  qof_instance_set_dirty (QOF_INSTANCE (split));
2081  xaccTransCommitEdit (split->parent);
2082 }
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 1500 of file Split.c.

1501 {
1502  int retval;
1503  int comp;
1504  const char *da, *db;
1505  gboolean action_for_num;
1506 
1507  if (sa == sb) return 0;
1508  /* nothing is always less than something */
1509  if (!sa) return -1;
1510  if (!sb) return +1;
1511 
1512  /* sort in transaction order, but use split action rather than trans num
1513  * according to book option */
1515  (xaccSplitGetBook (sa));
1516  if (action_for_num)
1517  retval = xaccTransOrder_num_action (sa->parent, sa->action,
1518  sb->parent, sb->action);
1519  else
1520  retval = xaccTransOrder (sa->parent, sb->parent);
1521  if (retval) return retval;
1522 
1523  /* otherwise, sort on memo strings */
1524  da = sa->memo ? sa->memo : "";
1525  db = sb->memo ? sb->memo : "";
1526  retval = g_utf8_collate (da, db);
1527  if (retval)
1528  return retval;
1529 
1530  /* otherwise, sort on action strings */
1531  da = sa->action ? sa->action : "";
1532  db = sb->action ? sb->action : "";
1533  retval = g_utf8_collate (da, db);
1534  if (retval != 0)
1535  return retval;
1536 
1537  /* the reconciled flag ... */
1538  if (sa->reconciled < sb->reconciled) return -1;
1539  if (sa->reconciled > sb->reconciled) return +1;
1540 
1541  /* compare amounts */
1543  if (comp < 0) return -1;
1544  if (comp > 0) return +1;
1545 
1547  if (comp < 0) return -1;
1548  if (comp > 0) return +1;
1549 
1550  /* if dates differ, return */
1551  if (sa->date_reconciled < sb->date_reconciled)
1552  return -1;
1553  else if (sa->date_reconciled > sb->date_reconciled)
1554  return 1;
1555 
1556  /* else, sort on guid - keeps sort stable. */
1557  retval = qof_instance_guid_compare(sa, sb);
1558  if (retval) return retval;
1559 
1560  return 0;
1561 }
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.c:1969
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.
Definition: Transaction.c:1930
gnc_numeric xaccSplitGetValue(const Split *split)
Returns the value of this split in the transaction&#39;s commodity.
Definition: Split.c:1921
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.
Definition: Transaction.c:1894
gnc_numeric xaccSplitGetAmount(const Split *split)
Returns the amount of the split in the account&#39;s commodity.
Definition: Split.c:1915

◆ 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 2057 of file Split.c.

2058 {
2059  const GncGUID* guid;
2060 
2061  g_return_if_fail (split != NULL);
2062  g_return_if_fail (other_split != NULL);
2063 
2064  guid = qof_instance_get_guid (QOF_INSTANCE (other_split));
2065  xaccTransBeginEdit (split->parent);
2066  qof_instance_kvp_remove_guid (QOF_INSTANCE (split), "lot-split",
2067  "peer_guid", guid);
2068  mark_split (split);
2069  qof_instance_set_dirty (QOF_INSTANCE (split));
2070  xaccTransCommitEdit (split->parent);
2071 }
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 1747 of file Split.c.

1748 {
1749  if (!split || !actn) return;
1750  xaccTransBeginEdit (split->parent);
1751 
1752  CACHE_REPLACE(split->action, actn);
1753  qof_instance_set_dirty(QOF_INSTANCE(split));
1754  xaccTransCommitEdit(split->parent);
1755 
1756 }
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 1319 of file Split.c.

1321 {
1322  const gnc_commodity *currency;
1323  const gnc_commodity *commodity;
1324 
1325  if (!s) return;
1326  xaccTransBeginEdit (s->parent);
1327 
1328  if (!s->acc)
1329  {
1330  PERR ("split must have a parent account");
1331  return;
1332  }
1333 
1334  currency = xaccTransGetCurrency (s->parent);
1335  commodity = xaccAccountGetCommodity (s->acc);
1336 
1337  /* If the base_currency is the transaction's commodity ('currency'),
1338  * set the value. If it's the account commodity, set the
1339  * amount. If both, set both. */
1340  if (gnc_commodity_equiv(currency, base_currency))
1341  {
1342  if (gnc_commodity_equiv(commodity, base_currency))
1343  {
1344  s->amount = gnc_numeric_convert(value,
1345  get_commodity_denom(s),
1347  }
1348  s->value = gnc_numeric_convert(value,
1349  get_currency_denom(s),
1351  }
1352  else if (gnc_commodity_equiv(commodity, base_currency))
1353  {
1354  s->amount = gnc_numeric_convert(value, get_commodity_denom(s),
1356  }
1357  else
1358  {
1359  PERR ("inappropriate base currency %s "
1360  "given split currency=%s and commodity=%s\n",
1361  gnc_commodity_get_printname(base_currency),
1362  gnc_commodity_get_printname(currency),
1363  gnc_commodity_get_printname(commodity));
1364  return;
1365  }
1366 
1367  SET_GAINS_A_VDIRTY(s);
1368  mark_split (s);
1369  qof_instance_set_dirty(QOF_INSTANCE(s));
1370  xaccTransCommitEdit(s->parent);
1371 }
#define PERR(format, args...)
Log a serious error.
Definition: qoflog.h:244
Round to the nearest integer, rounding away from zero when there are two equidistant nearest integers...
Definition: gnc-numeric.h:166
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:3405
gnc_commodity * xaccTransGetCurrency(const Transaction *trans)
Returns the valuation commodity of this transaction.
Definition: Transaction.c:1366
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 122 of file gmock-Split.cpp.

123 {
124  ASSERT_TRUE(GNC_IS_MOCKSPLIT(split));
125  gnc_mocksplit(split)->set_date_reconciled_secs(secs);
126 }

◆ 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 1728 of file Split.c.

1729 {
1730  if (!split || !memo) return;
1731  xaccTransBeginEdit (split->parent);
1732 
1733  CACHE_REPLACE(split->memo, memo);
1734  qof_instance_set_dirty(QOF_INSTANCE(split));
1735  xaccTransCommitEdit(split->parent);
1736 
1737 }
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...

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

116 {
117  ASSERT_TRUE(GNC_IS_MOCKSPLIT(split));
118  gnc_mocksplit(split)->set_reconcile(recn);
119 }

◆ 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 1196 of file Split.c.

1197 {
1198  if (!s) return;
1199  ENTER (" ");
1200  xaccTransBeginEdit (s->parent);
1201 
1202  s->value = gnc_numeric_mul(xaccSplitGetAmount(s),
1203  price, get_currency_denom(s),
1205 
1206  SET_GAINS_VDIRTY(s);
1207  mark_split (s);
1208  qof_instance_set_dirty(QOF_INSTANCE(s));
1209  xaccTransCommitEdit(s->parent);
1210  LEAVE ("");
1211 }
#define ENTER(format, args...)
Print a function entry debugging message.
Definition: qoflog.h:272
Round to the nearest integer, rounding away from zero when there are two equidistant nearest integers...
Definition: gnc-numeric.h:166
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
gnc_numeric xaccSplitGetAmount(const Split *split)
Returns the amount of the split in the account&#39;s commodity.
Definition: Split.c:1915

◆ 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 1168 of file Split.c.

1169 {
1170  if (!s) return;
1171  ENTER (" ");
1172  xaccTransBeginEdit (s->parent);
1173 
1174  s->amount = gnc_numeric_convert(amt, get_commodity_denom(s),
1176  s->value = gnc_numeric_mul(s->amount, price,
1177  get_currency_denom(s), GNC_HOW_RND_ROUND_HALF_UP);
1178 
1179  SET_GAINS_A_VDIRTY(s);
1180  mark_split (s);
1181  qof_instance_set_dirty(QOF_INSTANCE(s));
1182  xaccTransCommitEdit(s->parent);
1183  LEAVE ("");
1184 }
#define ENTER(format, args...)
Print a function entry debugging message.
Definition: qoflog.h:272
Round to the nearest integer, rounding away from zero when there are two equidistant nearest integers...
Definition: gnc-numeric.h:166
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

◆ 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 2127 of file Split.c.

2128 {
2129  GValue v = G_VALUE_INIT;
2130  gnc_numeric *num = NULL;
2131  gnc_numeric retval;
2132  g_return_val_if_fail(split, gnc_numeric_zero());
2133  qof_instance_get_kvp (QOF_INSTANCE (split), &v, 1, void_former_amt_str);
2134  if (G_VALUE_HOLDS_BOXED (&v))
2135  num = (gnc_numeric*)g_value_get_boxed (&v);
2136  retval = num ? *num : gnc_numeric_zero();
2137  g_value_unset (&v);
2138  return retval;
2139 }
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 2142 of file Split.c.

2143 {
2144  GValue v = G_VALUE_INIT;
2145  gnc_numeric *num = NULL;
2146  gnc_numeric retval;
2147  g_return_val_if_fail(split, gnc_numeric_zero());
2148  qof_instance_get_kvp (QOF_INSTANCE (split), &v, 1, void_former_val_str);
2149  if (G_VALUE_HOLDS_BOXED (&v))
2150  num = (gnc_numeric*)g_value_get_boxed (&v);
2151  retval = num ? *num : gnc_numeric_zero();
2152  g_value_unset (&v);
2153  return retval;
2154 }
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 }

◆ 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 750 of file Transaction.c.

752 {
753  gboolean change_accounts = FALSE;
754  GList *node;
755 
756  if (!from_trans || !to_trans)
757  return;
758 
759  change_accounts = from_acc && GNC_IS_ACCOUNT(to_acc) && from_acc != to_acc;
760  xaccTransBeginEdit(to_trans);
761 
762  FOR_EACH_SPLIT(to_trans, xaccSplitDestroy(s));
763  g_list_free(to_trans->splits);
764  to_trans->splits = NULL;
765 
766  xaccTransSetCurrency(to_trans, xaccTransGetCurrency(from_trans));
767  xaccTransSetDescription(to_trans, xaccTransGetDescription(from_trans));
768 
769  if ((xaccTransGetNum(to_trans) == NULL) || (g_strcmp0 (xaccTransGetNum(to_trans), "") == 0))
770  xaccTransSetNum(to_trans, xaccTransGetNum(from_trans));
771 
772  xaccTransSetNotes(to_trans, xaccTransGetNotes(from_trans));
773  xaccTransSetDocLink(to_trans, xaccTransGetDocLink (from_trans));
774  if(!no_date)
775  {
776  xaccTransSetDatePostedSecs(to_trans, xaccTransRetDatePosted (from_trans));
777  }
778 
779  /* Each new split will be parented to 'to' */
780  for (node = from_trans->splits; node; node = node->next)
781  {
782  Split *new_split = xaccMallocSplit( qof_instance_get_book(QOF_INSTANCE(from_trans)));
783  xaccSplitCopyOnto(node->data, new_split);
784  if (change_accounts && xaccSplitGetAccount(node->data) == from_acc)
785  xaccSplitSetAccount(new_split, to_acc);
786  xaccSplitSetParent(new_split, to_trans);
787  }
788  xaccTransCommitEdit(to_trans);
789 }
QofBook * qof_instance_get_book(gconstpointer inst)
Return the book pointer.
gboolean xaccSplitDestroy(Split *split)
Destructor.
Definition: Split.c:1470
void xaccTransSetNotes(Transaction *trans, const char *notes)
Sets the transaction Notes.
Definition: Transaction.c:2242
void xaccSplitCopyOnto(const Split *from_split, Split *to_split)
This is really a helper for xaccTransCopyOnto.
Definition: Split.c:639
void xaccTransSetDescription(Transaction *trans, const char *desc)
Sets the transaction Description.
Definition: Transaction.c:2192
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.
Definition: Transaction.c:2172
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.
Definition: Transaction.c:2405
const char * xaccTransGetDocLink(const Transaction *trans)
Gets the transaction Document Link.
Definition: Transaction.c:2417
void xaccTransSetCurrency(Transaction *trans, gnc_commodity *curr)
Set a new currency on a transaction.
Definition: Transaction.c:1425
const char * xaccTransGetNotes(const Transaction *trans)
Gets the transaction Notes.
Definition: Transaction.c:2432
time64 xaccTransRetDatePosted(const Transaction *trans)
Retrieve the posted date of the transaction.
Definition: Transaction.c:2484
const char * xaccTransGetDescription(const Transaction *trans)
Gets the transaction Description.
Definition: Transaction.c:2411
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1653
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1454
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)).
Definition: Transaction.c:2017
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.
Definition: Transaction.c:1366
void xaccTransSetDocLink(Transaction *trans, const char *doclink)
Sets the transaction Document Link.
Definition: Transaction.c:2203

◆ 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 710 of file Transaction.c.

711 {
712  Transaction *to_trans;
713 
714  if (!from_trans)
715  return NULL;
716 
717  to_trans = dupe_trans(from_trans);
718  return to_trans;
719 }

◆ xaccTransCountSplits()

int xaccTransCountSplits ( const Transaction *  trans)

Returns the number of splits in this transaction.

Definition at line 2396 of file Transaction.c.

2397 {
2398  gint i = 0;
2399  g_return_val_if_fail (trans != NULL, 0);
2400  FOR_EACH_SPLIT(trans, i++);
2401  return i;
2402 }

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

143 {
144  ASSERT_TRUE(GNC_IS_MOCKTRANSACTION(trans));
145  gnc_mocktransaction(trans)->destroy();
146 }

◆ 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 874 of file Transaction.c.

879 {
880  gboolean same_book;
881 
882  if (!ta && !tb) return TRUE; /* Arguable. FALSE may be better. */
883 
884  if (!ta || !tb)
885  {
886  PINFO ("one is NULL");
887  return FALSE;
888  }
889 
890  if (ta == tb) return TRUE;
891 
892  same_book = qof_instance_get_book(QOF_INSTANCE(ta)) == qof_instance_get_book(QOF_INSTANCE(tb));
893 
894  if (check_guids)
895  {
896  if (qof_instance_guid_compare(ta, tb) != 0)
897  {
898  PINFO ("GUIDs differ");
899  return FALSE;
900  }
901  }
902 
903  if (!gnc_commodity_equal(ta->common_currency, tb->common_currency))
904  {
905  PINFO ("commodities differ %s vs %s",
906  gnc_commodity_get_unique_name (ta->common_currency),
907  gnc_commodity_get_unique_name (tb->common_currency));
908  return FALSE;
909  }
910 
911  if (ta->date_entered != tb->date_entered)
912  {
913  char buf1[100];
914  char buf2[100];
915 
916  (void)gnc_time64_to_iso8601_buff(ta->date_entered, buf1);
917  (void)gnc_time64_to_iso8601_buff(tb->date_entered, buf2);
918  PINFO ("date entered differs: '%s' vs '%s'", buf1, buf2);
919  return FALSE;
920  }
921 
922  if (ta->date_posted != tb->date_posted)
923  {
924  char buf1[100];
925  char buf2[100];
926 
927  (void)gnc_time64_to_iso8601_buff(ta->date_posted, buf1);
928  (void)gnc_time64_to_iso8601_buff(tb->date_posted, buf2);
929  PINFO ("date posted differs: '%s' vs '%s'", buf1, buf2);
930  return FALSE;
931  }
932 
933  /* If the same book, since we use cached strings, we can just compare pointer
934  * equality for num and description
935  */
936  if ((same_book && ta->num != tb->num) || (!same_book && g_strcmp0(ta->num, tb->num) != 0))
937  {
938  PINFO ("num differs: %s vs %s", ta->num, tb->num);
939  return FALSE;
940  }
941 
942  if ((same_book && ta->description != tb->description)
943  || (!same_book && g_strcmp0(ta->description, tb->description)))
944  {
945  PINFO ("descriptions differ: %s vs %s", ta->description, tb->description);
946  return FALSE;
947  }
948 
949  if (qof_instance_compare_kvp (QOF_INSTANCE (ta), QOF_INSTANCE (tb)) != 0)
950  {
951  char *frame_a;
952  char *frame_b;
953 
954  frame_a = qof_instance_kvp_as_string (QOF_INSTANCE (ta));
955  frame_b = qof_instance_kvp_as_string (QOF_INSTANCE (tb));
956 
957 
958  PINFO ("kvp frames differ:\n%s\n\nvs\n\n%s", frame_a, frame_b);
959 
960  g_free (frame_a);
961  g_free (frame_b);
962 
963  return FALSE;
964  }
965 
966  if (check_splits)
967  {
968  if ((!ta->splits && tb->splits) || (!tb->splits && ta->splits))
969  {
970  PINFO ("only one has splits");
971  return FALSE;
972  }
973 
974  if (ta->splits && tb->splits)
975  {
976  GList *node_a, *node_b;
977 
978  for (node_a = ta->splits, node_b = tb->splits;
979  node_a;
980  node_a = node_a->next, node_b = node_b->next)
981  {
982  Split *split_a = node_a->data;
983  Split *split_b;
984 
985  /* don't presume that the splits are in the same order */
986  if (!assume_ordered)
987  node_b = g_list_find_custom (tb->splits, split_a,
988  compare_split_guids);
989 
990  if (!node_b)
991  {
992  gchar guidstr[GUID_ENCODING_LENGTH+1];
993  guid_to_string_buff (xaccSplitGetGUID (split_a),guidstr);
994 
995  PINFO ("first has split %s and second does not",guidstr);
996  return FALSE;
997  }
998 
999  split_b = node_b->data;
1000 
1001  if (!xaccSplitEqual (split_a, split_b, check_guids, check_balances,
1002  FALSE))
1003  {
1004  char str_a[GUID_ENCODING_LENGTH + 1];
1005  char str_b[GUID_ENCODING_LENGTH + 1];
1006 
1007  guid_to_string_buff (xaccSplitGetGUID (split_a), str_a);
1008  guid_to_string_buff (xaccSplitGetGUID (split_b), str_b);
1009 
1010  PINFO ("splits %s and %s differ", str_a, str_b);
1011  return FALSE;
1012  }
1013  }
1014 
1015  if (g_list_length (ta->splits) != g_list_length (tb->splits))
1016  {
1017  PINFO ("different number of splits");
1018  return FALSE;
1019  }
1020  }
1021  }
1022 
1023  return TRUE;
1024 }
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:174
gboolean xaccSplitEqual(const Split *sa, const Split *sb, gboolean check_guids, gboolean check_balances, gboolean check_txn_splits)
Equality.
Definition: Split.c:769
#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:554
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:1142

◆ xaccTransGetAccountAmount()

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

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

Definition at line 1204 of file Transaction.c.

1205 {
1206  gnc_numeric total = gnc_numeric_zero ();
1207  if (!trans || !acc) return total;
1208 
1209  total = gnc_numeric_convert (total, xaccAccountGetCommoditySCU (acc),
1211  FOR_EACH_SPLIT(trans, if (acc == xaccSplitGetAccount(s))
1212  total = gnc_numeric_add_fixed(
1213  total, xaccSplitGetAmount(s)));
1214  return total;
1215 }
int xaccAccountGetCommoditySCU(const Account *acc)
Return the SCU for the account.
Definition: Account.cpp:2682
Round to the nearest integer, rounding away from zero when there are two equidistant nearest integers...
Definition: gnc-numeric.h:166
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
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 1328 of file Transaction.c.

1330 {
1331  GList *node;
1332  Split *last_split = NULL;
1333 
1334  // Not really the appropriate error value.
1335  g_return_val_if_fail(account && trans, gnc_numeric_error(GNC_ERROR_ARG));
1336 
1337  for (node = trans->splits; node; node = node->next)
1338  {
1339  Split *split = node->data;
1340 
1341  if (!xaccTransStillHasSplit(trans, split))
1342  continue;
1343  if (xaccSplitGetAccount(split) != account)
1344  continue;
1345 
1346  if (!last_split)
1347  {
1348  last_split = split;
1349  continue;
1350  }
1351 
1352  /* This test needs to correspond to the comparison function used when
1353  sorting the splits for computing the running balance. */
1354  if (xaccSplitOrder (last_split, split) < 0)
1355  last_split = split;
1356  }
1357 
1358  return xaccSplitGetBalance (last_split);
1359 }
gint xaccSplitOrder(const Split *sa, const Split *sb)
The xaccSplitOrder(sa,sb) method is useful for sorting.
Definition: Split.c:1500
gnc_numeric xaccSplitGetBalance(const Split *s)
Returns the running balance up to and including the indicated split.
Definition: Split.c:1295
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:225
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 1188 of file Transaction.c.

1190 {
1191  gnc_numeric total = gnc_numeric_zero ();
1192  if (!trans || !acc) return total;
1193 
1194  FOR_EACH_SPLIT(trans, if (acc == xaccSplitGetAccount(s))
1195 {
1196  total = gnc_numeric_add (total, xaccSplitGetValue (s),
1199  });
1200  return total;
1201 }
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:189
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:246

◆ 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 2333 of file Transaction.c.

2334 {
2335  GList *apar_splits = NULL;
2336  if (!trans) return NULL;
2337 
2338  FOR_EACH_SPLIT (trans,
2339  const Account *account = xaccSplitGetAccount(s);
2340  if (account && xaccAccountIsAPARType(xaccAccountGetType(account)))
2341  {
2342 
2343  if (!strict)
2344  apar_splits = g_list_prepend (apar_splits, s);
2345  else
2346  {
2347  GncOwner owner;
2348  GNCLot *lot = xaccSplitGetLot(s);
2349  if (lot &&
2350  (gncInvoiceGetInvoiceFromLot (lot) ||
2351  gncOwnerGetOwnerFromLot (lot, &owner)))
2352  apar_splits = g_list_prepend (apar_splits, s);
2353  }
2354  }
2355  );
2356 
2357  apar_splits = g_list_reverse (apar_splits);
2358  return apar_splits;
2359 }
GNCAccountType xaccAccountGetType(const Account *acc)
Returns the account&#39;s account type.
Definition: Account.cpp:3236
gboolean gncOwnerGetOwnerFromLot(GNCLot *lot, GncOwner *owner)
Get the owner from the lot.
Definition: gncOwner.c:637
gboolean xaccAccountIsAPARType(GNCAccountType t)
Convenience function to check if the account is a valid business account type (meaning an Accounts Pa...
Definition: Account.cpp:4613
GncInvoice * gncInvoiceGetInvoiceFromLot(GNCLot *lot)
Given a LOT, find and return the Invoice attached to the lot.
Definition: gncInvoice.c:1301
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.c:1881

◆ 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 1366 of file Transaction.c.

1367 {
1368  return trans ? trans->common_currency : NULL;
1369 }

◆ 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 2477 of file Transaction.c.

2478 {
2479  return trans ? trans->date_entered : 0;
2480 }

◆ 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 2490 of file Transaction.c.

2491 {
2492  GDate result;
2493  g_date_clear (&result, 1);
2494  if (trans)
2495  {
2496  /* Can we look up this value in the kvp slot? If yes, use it
2497  * from there because it doesn't suffer from time zone
2498  * shifts. */
2499  GValue v = G_VALUE_INIT;
2500  qof_instance_get_kvp (QOF_INSTANCE (trans), &v, 1, TRANS_DATE_POSTED);
2501  if (G_VALUE_HOLDS_BOXED (&v))
2502  result = *(GDate*)g_value_get_boxed (&v);
2503  g_value_unset (&v);
2504  if (! g_date_valid (&result) || gdate_to_time64 (result) == INT64_MAX)
2505  {
2506  /* Well, this txn doesn't have a valid GDate saved in a slot.
2507  * time64_to_gdate() uses local time and we want UTC so we have
2508  * to write it out.
2509  */
2510  time64 time = xaccTransGetDate(trans);
2511  struct tm *stm = gnc_gmtime(&time);
2512  if (stm)
2513  {
2514  g_date_set_dmy(&result, stm->tm_mday,
2515  (GDateMonth)(stm->tm_mon + 1),
2516  stm->tm_year + 1900);
2517  free(stm);
2518  }
2519  }
2520  }
2521  return result;
2522 }
time64 xaccTransGetDate(const Transaction *trans)
Retrieve the posted date of the transaction.
Definition: Transaction.c:2470
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:1256
struct tm * gnc_gmtime(const time64 *secs)
fill out a time struct from a 64-bit time value
Definition: gnc-date.cpp:189
gint64 time64
Many systems, including Microsoft Windows and BSD-derived Unixes like Darwin, are retaining the int-3...
Definition: gnc-date.h:93

◆ 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 2372 of file Transaction.c.

2373 {
2374  FOR_EACH_SPLIT (trans,
2375  const Account *account = xaccSplitGetAccount(s);
2376  if (account && xaccAccountIsAPARType(xaccAccountGetType(account)))
2377  {
2378  GNCLot *lot;
2379  GncOwner owner;
2380 
2381  if (!strict)
2382  return s;
2383 
2384  lot = xaccSplitGetLot(s);
2385  if (lot &&
2386  (gncInvoiceGetInvoiceFromLot (lot) ||
2387  gncOwnerGetOwnerFromLot (lot, &owner)))
2388  return s;
2389  }
2390  );
2391 
2392  return NULL;
2393 }
GNCAccountType xaccAccountGetType(const Account *acc)
Returns the account&#39;s account type.
Definition: Account.cpp:3236
gboolean gncOwnerGetOwnerFromLot(GNCLot *lot, GncOwner *owner)
Get the owner from the lot.
Definition: gncOwner.c:637
gboolean xaccAccountIsAPARType(GNCAccountType t)
Convenience function to check if the account is a valid business account type (meaning an Accounts Pa...
Definition: Account.cpp:4613
GncInvoice * gncInvoiceGetInvoiceFromLot(GNCLot *lot)
Given a LOT, find and return the Invoice attached to the lot.
Definition: gncInvoice.c:1301
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.c:1881

◆ 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 2361 of file Transaction.c.

2362 {
2363  FOR_EACH_SPLIT (trans,
2364  const Account *account = xaccSplitGetAccount(s);
2365  if (account && gncBusinessIsPaymentAcctType(xaccAccountGetType(account)))
2366  return s;
2367  );
2368 
2369  return NULL;
2370 }
GNCAccountType xaccAccountGetType(const Account *acc)
Returns the account&#39;s account type.
Definition: Account.cpp:3236
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 1070 of file Transaction.c.

1071 {
1072  /* imbal_value is used if either (1) the transaction has a non currency
1073  split or (2) all the splits are in the same currency. If there are
1074  no non-currency splits and not all splits are in the same currency then
1075  imbal_list is used to compute the imbalance. */
1076  MonetaryList *imbal_list = NULL;
1077  gnc_numeric imbal_value = gnc_numeric_zero();
1078  gboolean trading_accts;
1079 
1080  if (!trans) return imbal_list;
1081 
1082  ENTER("(trans=%p)", trans);
1083 
1084  trading_accts = xaccTransUseTradingAccounts (trans);
1085 
1086  /* If using trading accounts and there is at least one split that is not
1087  in the transaction currency or a split that has a price or exchange
1088  rate other than 1, then compute the balance in each commodity in the
1089  transaction. Otherwise (all splits are in the transaction's currency)
1090  then compute the balance using the value fields.
1091 
1092  Optimize for the common case of only one currency and a balanced
1093  transaction. */
1094  FOR_EACH_SPLIT(trans,
1095  {
1096  gnc_commodity *commodity;
1098  if (trading_accts &&
1099  (imbal_list ||
1100  ! gnc_commodity_equiv(commodity, trans->common_currency) ||
1102  {
1103  /* Need to use (or already are using) a list of imbalances in each of
1104  the currencies used in the transaction. */
1105  if (! imbal_list)
1106  {
1107  /* All previous splits have been in the transaction's common
1108  currency, so imbal_value is in this currency. */
1109  imbal_list = gnc_monetary_list_add_value(imbal_list,
1110  trans->common_currency,
1111  imbal_value);
1112  }
1113  imbal_list = gnc_monetary_list_add_value(imbal_list, commodity,
1114  xaccSplitGetAmount(s));
1115  }
1116 
1117  /* Add it to the value accumulator in case we need it. */
1118  imbal_value = gnc_numeric_add(imbal_value, xaccSplitGetValue(s),
1120  } );
1121 
1122 
1123  if (!imbal_list && !gnc_numeric_zero_p(imbal_value))
1124  {
1125  /* Not balanced and no list, create one. If we found multiple currencies
1126  and no non-currency commodity then imbal_list will already exist and
1127  we won't get here. */
1128  imbal_list = gnc_monetary_list_add_value(imbal_list,
1129  trans->common_currency,
1130  imbal_value);
1131  }
1132 
1133  /* Delete all the zero entries from the list, perhaps leaving an
1134  empty list */
1135  imbal_list = gnc_monetary_list_delete_zeros(imbal_list);
1136 
1137  LEAVE("(trans=%p), imbal=%p", trans, imbal_list);
1138  return imbal_list;
1139 }
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.
Definition: Transaction.c:1033
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:189
#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:3405
#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:246
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 2319 of file Transaction.c.

2320 {
2321  GList *pay_splits = NULL;
2322  FOR_EACH_SPLIT (trans,
2323  const Account *account = xaccSplitGetAccount(s);
2324  if (account && gncBusinessIsPaymentAcctType(xaccAccountGetType(account)))
2325  pay_splits = g_list_prepend (pay_splits, s);
2326  );
2327 
2328  pay_splits = g_list_reverse (pay_splits);
2329  return pay_splits;
2330 }
GNCAccountType xaccAccountGetType(const Account *acc)
Returns the account&#39;s account type.
Definition: Account.cpp:3236
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 2567 of file Transaction.c.

2568 {
2569  if (!trans)
2570  return NULL;
2571 
2572  if (trans->readonly_reason == is_unset)
2573  {
2574  GValue v = G_VALUE_INIT;
2575  qof_instance_get_kvp (QOF_INSTANCE(trans), &v, 1, TRANS_READ_ONLY_REASON);
2576  trans->readonly_reason = G_VALUE_HOLDS_STRING (&v) ?
2577  g_value_dup_string (&v) : NULL;
2578  g_value_unset (&v);
2579  }
2580  return trans->readonly_reason;
2581 }
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 2908 of file Transaction.c.

2909 {
2910  GValue v = G_VALUE_INIT;
2911  Transaction *retval = NULL;
2912  g_return_val_if_fail(trans, NULL);
2913  qof_instance_get_kvp (QOF_INSTANCE(trans), &v, 1, TRANS_REVERSED_BY);
2914  if (G_VALUE_HOLDS_BOXED (&v))
2915  {
2916  GncGUID* guid = g_value_get_boxed (&v);
2917  retval = xaccTransLookup(guid, qof_instance_get_book (trans));
2918  }
2919  g_value_unset (&v);
2920  return retval;
2921 }
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...
Definition: Transaction.c:1042
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 ( const Transaction *  trans)

Returns the Transaction Type.

See TXN_TYPE_NONE, TXN_TYPE_INVOICE and TXN_TYPE_PAYMENT

Definition at line 2548 of file Transaction.c.

2549 {
2550  const char *s = NULL;
2551  GValue v = G_VALUE_INIT;
2552  char ret = TXN_TYPE_NONE;
2553 
2554  if (!trans) return TXN_TYPE_NONE;
2555  qof_instance_get_kvp (QOF_INSTANCE (trans), &v, 1, TRANS_TXN_TYPE_KVP);
2556  if (G_VALUE_HOLDS_STRING (&v))
2557  {
2558  s = g_value_get_string (&v);
2559  if (s && strlen (s) == 1)
2560  ret = s[0];
2561  }
2562  g_value_unset (&v);
2563  return ret;
2564 }
void qof_instance_get_kvp(QofInstance *, GValue *value, unsigned count,...)
Retrieves the contents of a KVP slot into a provided GValue.
#define TXN_TYPE_NONE
No transaction type.
Definition: Transaction.h:124

◆ 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 2806 of file Transaction.c.

2807 {
2808  g_return_val_if_fail (trans, NULL);
2809  if (trans->void_reason == is_unset)
2810  {
2811  GValue v = G_VALUE_INIT;
2812  Transaction *t = (Transaction*) trans;
2813  qof_instance_get_kvp (QOF_INSTANCE (trans), &v, 1, void_reason_str);
2814  t->void_reason = G_VALUE_HOLDS_STRING (&v) ? g_value_dup_string (&v) : NULL;
2815  g_value_unset (&v);
2816  }
2817  return trans->void_reason;
2818 }
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 2799 of file Transaction.c.

2800 {
2801  const char *s = xaccTransGetVoidReason (trans);
2802  return (s && *s);
2803 }
const char * xaccTransGetVoidReason(const Transaction *trans)
Returns the user supplied textual reason why a transaction was voided.
Definition: Transaction.c:2806

◆ 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 2821 of file Transaction.c.

2822 {
2823  GValue v = G_VALUE_INIT;
2824  const char *s = NULL;
2825  time64 void_time = 0;
2826 
2827  g_return_val_if_fail(tr, void_time);
2828  qof_instance_get_kvp (QOF_INSTANCE (tr), &v, 1, void_time_str);
2829  if (G_VALUE_HOLDS_STRING (&v))
2830  {
2831  s = g_value_get_string (&v);
2832  if (s)
2833  void_time = gnc_iso8601_to_time64_gmt (s);
2834  }
2835  g_value_unset (&v);
2836  return void_time;
2837 }
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
Many systems, including Microsoft Windows and BSD-derived Unixes like Darwin, are retaining the int-3...
Definition: gnc-date.h:93

◆ xaccTransIsBalanced()

gboolean xaccTransIsBalanced ( const Transaction *  trans)

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

Definition at line 1142 of file Transaction.c.

1143 {
1144  MonetaryList *imbal_list;
1145  gboolean result;
1146  gnc_numeric imbal = gnc_numeric_zero();
1147  gnc_numeric imbal_trading = gnc_numeric_zero();
1148 
1149  if (trans == NULL) return FALSE;
1150 
1151  if (xaccTransUseTradingAccounts(trans))
1152  {
1153  /* Transaction is imbalanced if the value is imbalanced in either
1154  trading or non-trading splits. One can't be used to balance
1155  the other. */
1156  FOR_EACH_SPLIT(trans,
1157  {
1158  Account *acc = xaccSplitGetAccount(s);
1159  if (!acc || xaccAccountGetType(acc) != ACCT_TYPE_TRADING)
1160  {
1161  imbal = gnc_numeric_add(imbal, xaccSplitGetValue(s),
1163  }
1164  else
1165  {
1166  imbal_trading = gnc_numeric_add(imbal_trading, xaccSplitGetValue(s),
1168  }
1169  }
1170  );
1171  }
1172  else
1173  imbal = xaccTransGetImbalanceValue(trans);
1174 
1175  if (! gnc_numeric_zero_p(imbal) || ! gnc_numeric_zero_p(imbal_trading))
1176  return FALSE;
1177 
1178  if (!xaccTransUseTradingAccounts (trans))
1179  return TRUE;
1180 
1181  imbal_list = xaccTransGetImbalance(trans);
1182  result = imbal_list == NULL;
1183  gnc_monetary_list_free(imbal_list);
1184  return result;
1185 }
gboolean xaccTransUseTradingAccounts(const Transaction *trans)
Determine whether this transaction should use commodity trading accounts.
Definition: Transaction.c:1033
GNCAccountType xaccAccountGetType(const Account *acc)
Returns the account&#39;s account type.
Definition: Account.cpp:3236
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:189
Account used to record multiple commodity transactions.
Definition: Account.h:158
gnc_numeric xaccTransGetImbalanceValue(const Transaction *trans)
The xaccTransGetImbalanceValue() method returns the total value of the transaction.
Definition: Transaction.c:1054
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 ...
Definition: Transaction.c:1070
#define GNC_DENOM_AUTO
Values that can be passed as the &#39;denom&#39; argument.
Definition: gnc-numeric.h:246

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

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

◆ 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 2606 of file Transaction.c.

2607 {
2608  GDate *threshold_date;
2609  GDate trans_date;
2610  const QofBook *book = xaccTransGetBook (trans);
2611  gboolean result;
2612  g_assert(trans);
2613 
2614  if (!qof_book_uses_autoreadonly(book))
2615  {
2616  return FALSE;
2617  }
2618 
2619  if (xaccTransIsSXTemplate (trans))
2620  return FALSE;
2621 
2622  threshold_date = qof_book_get_autoreadonly_gdate(book);
2623  g_assert(threshold_date); // ok because we checked uses_autoreadonly before
2624  trans_date = xaccTransGetDatePostedGDate(trans);
2625 
2626 // g_warning("there is auto-read-only with days=%d, trans_date_day=%d, threshold_date_day=%d",
2627 // qof_book_get_num_days_autofreeze(book),
2628 // g_date_get_day(&trans_date),
2629 // g_date_get_day(threshold_date));
2630 
2631  if (g_date_compare(&trans_date, threshold_date) < 0)
2632  {
2633  //g_warning("we are auto-read-only");
2634  result = TRUE;
2635  }
2636  else
2637  {
2638  result = FALSE;
2639  }
2640  g_date_free(threshold_date);
2641  return result;
2642 }
GDate * qof_book_get_autoreadonly_gdate(const QofBook *book)
Returns the GDate that is the threshold for auto-read-only.
Definition: qofbook.cpp:1112
#define xaccTransGetBook(X)
Definition: Transaction.h:783
gboolean qof_book_uses_autoreadonly(const QofBook *book)
Returns TRUE if the auto-read-only feature should be used, otherwise FALSE.
Definition: qofbook.cpp:1086
GDate xaccTransGetDatePostedGDate(const Transaction *trans)
Retrieve the posted date of the transaction.
Definition: Transaction.c:2490

◆ 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 1042 of file Transaction.c.

1043 {
1044  QofCollection *col;
1045  if (!guid || !book) return NULL;
1046  col = qof_book_get_collection (book, GNC_ID_TRANS);
1047  return (Transaction *) qof_collection_lookup_entity (col, guid);
1048 }
QofInstance * qof_collection_lookup_entity(const QofCollection *col, const GncGUID *guid)
Find the entity going only from its guid.
Definition: qofid.cpp:215
QofCollection * qof_book_get_collection(const QofBook *book, QofIdType entity_type)
Return The table of entities of the given type.
Definition: qofbook.cpp:604

◆ 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 1894 of file Transaction.c.

1895 {
1896  return xaccTransOrder_num_action (ta, NULL, tb, NULL);
1897 }
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.
Definition: Transaction.c:1930

◆ 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 1930 of file Transaction.c.

1932 {
1933  const char *da, *db;
1934  int retval;
1935  int64_t na, nb;
1936 
1937  if ( ta && !tb ) return -1;
1938  if ( !ta && tb ) return +1;
1939  if ( !ta && !tb ) return 0;
1940 
1941  if (ta->date_posted != tb->date_posted)
1942  return (ta->date_posted > tb->date_posted) - (ta->date_posted < tb->date_posted);
1943 
1944  /* Always sort closing transactions after normal transactions */
1945  {
1946  gboolean ta_is_closing = xaccTransGetIsClosingTxn (ta);
1947  gboolean tb_is_closing = xaccTransGetIsClosingTxn (tb);
1948  if (ta_is_closing != tb_is_closing)
1949  return (ta_is_closing - tb_is_closing);
1950  }
1951 
1952  /* otherwise, sort on number string */
1953  if (actna && actnb) /* split action string, if not NULL */
1954  {
1955  retval = order_by_int64_or_string (actna, actnb);
1956  }
1957  else /* else transaction num string */
1958  {
1959  retval = order_by_int64_or_string (ta->num, tb->num);
1960  }
1961  if (retval)
1962  return retval;
1963 
1964  if (ta->date_entered != tb->date_entered)
1965  return (ta->date_entered > tb->date_entered) - (ta->date_entered < tb->date_entered);
1966 
1967  /* otherwise, sort on description string */
1968  da = ta->description ? ta->description : "";
1969  db = tb->description ? tb->description : "";
1970  retval = g_utf8_collate (da, db);
1971  if (retval)
1972  return retval;
1973 
1974  /* else, sort on guid - keeps sort stable. */
1975  return qof_instance_guid_compare(ta, tb);
1976 }
gboolean xaccTransGetIsClosingTxn(const Transaction *trans)
Returns whether this transaction is a "closing transaction".
Definition: Transaction.c:2447
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 149 of file gmock-Transaction.cpp.

150 {
151  g_return_if_fail(GNC_IS_MOCKTRANSACTION(trans));
152  ((MockTransaction*)trans)->recordPrice();
153 }

◆ 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 2525 of file Transaction.c.

2526 {
2527  return trans ? trans->date_entered : 0;
2528 }

◆ 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 2484 of file Transaction.c.

2485 {
2486  return trans ? trans->date_posted : 0;
2487 }

◆ 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 2868 of file Transaction.c.

2869 {
2870  Transaction *trans;
2871  GValue v = G_VALUE_INIT;
2872  g_return_val_if_fail(orig, NULL);
2873 
2874  /* First edit, dirty, and commit orig to ensure that any trading
2875  * splits are correctly balanced.
2876  */
2877  xaccTransBeginEdit (orig);
2878  qof_instance_set_dirty (QOF_INSTANCE (orig));
2879  xaccTransCommitEdit (orig);
2880 
2881  trans = xaccTransClone(orig);
2882  g_return_val_if_fail (trans, NULL);
2883  xaccTransBeginEdit(trans);
2884 
2885  /* Reverse the values on each split. Clear per-split info. */
2886  FOR_EACH_SPLIT(trans,
2887  {
2891  });
2892 
2893  /* Now update the original with a pointer to the new one */
2894  g_value_init (&v, GNC_TYPE_GUID);
2895  g_value_set_boxed (&v, xaccTransGetGUID(trans));
2896  qof_instance_set_kvp (QOF_INSTANCE (orig), &v, 1, TRANS_REVERSED_BY);
2897  g_value_unset (&v);
2898 
2899  /* Make sure the reverse transaction is not read-only */
2900  xaccTransClearReadOnly(trans);
2901 
2902  qof_instance_set_dirty(QOF_INSTANCE(trans));
2903  xaccTransCommitEdit(trans);
2904  return trans;
2905 }
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.
Definition: Transaction.c:681
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1653
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1454
#define xaccTransGetGUID(X)
Definition: Transaction.h:785
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 1728 of file Transaction.c.

1729 {
1730  GList *node, *onode;
1731  QofBackend *be;
1732  Transaction *orig;
1733  GList *slist;
1734  int num_preexist, i;
1735 
1736 /* FIXME: This isn't quite the right way to handle nested edits --
1737  * there should be a stack of transaction states that are popped off
1738  * and restored at each level -- but it does prevent restoring to the
1739  * editlevel 0 state until one is returning to editlevel 0, and
1740  * thereby prevents a crash caused by trans->orig getting NULLed too
1741  * soon.
1742  */
1743  if (!qof_instance_get_editlevel (QOF_INSTANCE (trans))) return;
1744  if (qof_instance_get_editlevel (QOF_INSTANCE (trans)) > 1) {
1745  qof_instance_decrease_editlevel (QOF_INSTANCE (trans));
1746  return;
1747  }
1748 
1749  ENTER ("trans addr=%p\n", trans);
1750 
1751  check_open(trans);
1752 
1753  /* copy the original values back in. */
1754 
1755  orig = trans->orig;
1756  SWAP_STR(trans->num, orig->num);
1757  SWAP_STR(trans->description, orig->description);
1758  trans->date_entered = orig->date_entered;
1759  trans->date_posted = orig->date_posted;
1760  SWAP(trans->common_currency, orig->common_currency);
1761  qof_instance_swap_kvp (QOF_INSTANCE (trans), QOF_INSTANCE (orig));
1762 
1763  /* The splits at the front of trans->splits are exactly the same
1764  splits as in the original, but some of them may have changed, so
1765  we restore only those. */
1766 /* FIXME: Runs off the transaction's splits, so deleted splits are not
1767  * restored!
1768  */
1769  num_preexist = g_list_length(orig->splits);
1770  slist = g_list_copy(trans->splits);
1771  for (i = 0, node = slist, onode = orig->splits; node;
1772  i++, node = node->next, onode = onode ? onode->next : NULL)
1773  {
1774  Split *s = node->data;
1775 
1776  if (!qof_instance_is_dirty(QOF_INSTANCE(s)))
1777  continue;
1778 
1779  if (i < num_preexist && onode)
1780  {
1781  Split *so = onode->data;
1782 
1783  xaccSplitRollbackEdit(s);
1784  SWAP_STR(s->action, so->action);
1785  SWAP_STR(s->memo, so->memo);
1786  qof_instance_copy_kvp (QOF_INSTANCE (s), QOF_INSTANCE (so));
1787  s->reconciled = so->reconciled;
1788  s->amount = so->amount;
1789  s->value = so->value;
1790  s->lot = so->lot;
1791  s->gains_split = so->gains_split;
1792  //SET_GAINS_A_VDIRTY(s);
1793  s->date_reconciled = so->date_reconciled;
1794  qof_instance_mark_clean(QOF_INSTANCE(s));
1795  xaccFreeSplit(so);
1796  }
1797  else
1798  {
1799  /* Potentially added splits */
1800  if (trans != xaccSplitGetParent(s))
1801  {
1802  trans->splits = g_list_remove(trans->splits, s);
1803  /* New split added, but then moved to another
1804  transaction */
1805  continue;
1806  }
1807  xaccSplitRollbackEdit(s);
1808  trans->splits = g_list_remove(trans->splits, s);
1809  g_assert(trans != xaccSplitGetParent(s));
1810  /* NB: our memory management policy here is that a new split
1811  added to the transaction which is then rolled-back still
1812  belongs to the engine. Specifically, it's freed by the
1813  transaction to which it was added. Don't add the Split to
1814  more than one transaction during the begin/commit block! */
1815  if (NULL == xaccSplitGetParent(s))
1816  {
1817  xaccFreeSplit(s); // a newly malloc'd split
1818  }
1819  }
1820  }
1821  g_list_free(slist);
1822  g_list_free(orig->splits);
1823  orig->splits = NULL;
1824 
1825  /* Now that the engine copy is back to its original version,
1826  * get the backend to fix it in the database */
1830  if (qof_backend_can_rollback (be))
1831  {
1832  QofBackendError errcode;
1833 
1834  /* clear errors */
1835  do
1836  {
1837  errcode = qof_backend_get_error (be);
1838  }
1839  while (ERR_BACKEND_NO_ERR != errcode);
1840 
1841  qof_backend_rollback_instance (be, &(trans->inst));
1842 
1843  errcode = qof_backend_get_error (be);
1844  if (ERR_BACKEND_MOD_DESTROY == errcode)
1845  {
1846  /* The backend is asking us to delete this transaction.
1847  * This typically happens because another (remote) user
1848  * has deleted this transaction, and we haven't found
1849  * out about it until this user tried to edit it.
1850  */
1851  xaccTransDestroy (trans);
1852  do_destroy (trans);
1853 
1854  /* push error back onto the stack */
1855  qof_backend_set_error (be, errcode);
1856  LEAVE ("deleted trans addr=%p\n", trans);
1857  return;
1858  }
1859  if (ERR_BACKEND_NO_ERR != errcode)
1860  {
1861  PERR ("Rollback Failed. Ouch!");
1862  /* push error back onto the stack */
1863  qof_backend_set_error (be, errcode);
1864  }
1865  }
1866 
1868  xaccTransWriteLog (trans, 'R');
1869 
1870  xaccFreeTransaction (trans->orig);
1871 
1872  trans->orig = NULL;
1873  qof_instance_set_destroying(trans, FALSE);
1874 
1875  /* Put back to zero. */
1876  qof_instance_decrease_editlevel(trans);
1877  /* FIXME: The register code seems to depend on the engine to
1878  generate an event during rollback, even though the state is just
1879  reverting to what it was. */
1880  gen_event_trans (trans);
1881 
1882  LEAVE ("trans addr=%p\n", trans);
1883 }
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:162
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.c: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.
Definition: Transaction.c:1476
gboolean qof_book_is_readonly(const QofBook *book)
Return whether the book is read only.
Definition: qofbook.cpp:580
#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:524

◆ 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 2981 of file Transaction.c.

2982 {
2983  SplitList *node;
2984 
2985  ENTER("(trans=%p)", trans);
2986  /* Lock down posted date, its to be synced to the posted date
2987  * for the source of the cap gains. */
2988  xaccTransScrubGainsDate(trans);
2989 
2990  /* Fix up the split amount */
2991 restart:
2992  for (node = trans->splits; node; node = node->next)
2993  {
2994  Split *s = node->data;
2995 
2996  if (!xaccTransStillHasSplit(trans, s)) continue;
2997 
2998  xaccSplitDetermineGainStatus(s);
2999  if (s->gains & GAINS_STATUS_ADIRTY)
3000  {
3001  gboolean altered = FALSE;
3002  s->gains &= ~GAINS_STATUS_ADIRTY;
3003  if (s->lot)
3004  altered = xaccScrubLot(s->lot);
3005  else
3006  altered = xaccSplitAssign(s);
3007  if (altered) goto restart;
3008  }
3009  }
3010 
3011  /* Fix up gains split value */
3012  FOR_EACH_SPLIT(trans,
3013  if ((s->gains & GAINS_STATUS_VDIRTY) ||
3014  (s->gains_split &&
3015  (s->gains_split->gains & GAINS_STATUS_VDIRTY)))
3016  xaccSplitComputeCapGains(s, gain_acc);
3017  );
3018 
3019  LEAVE("(trans=%p)", trans);
3020 }
void xaccSplitComputeCapGains(Split *split, Account *gain_acc)
The xaccSplitComputeCapGains() routine computes the cap gains or losses for the indicated split...
Definition: cap-gains.c:528
#define ENTER(format, args...)
Print a function entry debugging message.
Definition: qoflog.h:272
GList SplitList
GList of Split.
Definition: gnc-engine.h:211
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.c: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.c: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 1425 of file Transaction.c.

1426 {
1427  gnc_commodity *old_curr = trans->common_currency;
1428  if (!trans || !curr || trans->common_currency == curr) return;
1429  xaccTransBeginEdit(trans);
1430 
1431  trans->common_currency = curr;
1432  if (old_curr != NULL && trans->splits != NULL)
1433  {
1434  gnc_numeric rate = find_new_rate(trans, curr);
1435  if (!gnc_numeric_zero_p (rate))
1436  {
1437  FOR_EACH_SPLIT(trans, split_set_new_value(s, curr, old_curr, rate));
1438  }
1439  else
1440  {
1441  FOR_EACH_SPLIT(trans, xaccSplitSetValue(s, xaccSplitGetValue(s)));
1442  }
1443  }
1444 
1445  qof_instance_set_dirty(QOF_INSTANCE(trans));
1446  mark_trans(trans); /* Dirty balance of every account in trans */
1447  xaccTransCommitEdit(trans);
1448 }
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...
Definition: Transaction.c:1653
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1454
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 2078 of file Transaction.c.

2079 {
2080  GDate *date;
2081  if (!trans) return;
2082  date = g_date_new_dmy(day, mon, year);
2083  if (!g_date_valid(date))
2084  {
2085  PWARN("Attempted to set invalid date %d-%d-%d; set today's date instead.",
2086  year, mon, day);
2087  g_free(date);
2088  date = gnc_g_date_new_today();
2089  }
2090  xaccTransSetDatePostedGDate(trans, *date);
2091  g_free(date);
2092 }
void xaccTransSetDatePostedGDate(Transaction *trans, GDate date)
This method modifies posted date of the transaction, specified by a GDate.
Definition: Transaction.c:2033
#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:1229

◆ 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 2052 of file Transaction.c.

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

◆ 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 2033 of file Transaction.c.

2034 {
2035  GValue v = G_VALUE_INIT;
2036  if (!trans) return;
2037 
2038  /* We additionally save this date into a kvp frame to ensure in
2039  * the future a date which was set as *date* (without time) can
2040  * clearly be distinguished from the time64. */
2041  g_value_init (&v, G_TYPE_DATE);
2042  g_value_set_boxed (&v, &date);
2043  qof_instance_set_kvp (QOF_INSTANCE(trans), &v, 1, TRANS_DATE_POSTED);
2044  g_value_unset (&v);
2045  /* mark dirty and commit handled by SetDateInternal */
2046  xaccTransSetDateInternal(trans, &trans->date_posted,
2047  gdate_to_time64(date));
2048  set_gains_date_dirty (trans);
2049 }
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:1256

◆ 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 2017 of file Transaction.c.

2018 {
2019  if (!trans) return;
2020  xaccTransSetDateInternal(trans, &trans->date_posted, secs);
2021  set_gains_date_dirty(trans);
2022 }

◆ 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 2139 of file Transaction.c.

2140 {
2141  if (trans && reason)
2142  {
2143  GValue v = G_VALUE_INIT;
2144  g_value_init (&v, G_TYPE_STRING);
2145  g_value_set_string (&v, reason);
2146  xaccTransBeginEdit(trans);
2147  qof_instance_set_kvp (QOF_INSTANCE (trans), &v, 1, TRANS_READ_ONLY_REASON);
2148  qof_instance_set_dirty(QOF_INSTANCE(trans));
2149  g_value_unset (&v);
2150  xaccTransCommitEdit(trans);
2151 
2152  if (trans->readonly_reason != is_unset)
2153  g_free (trans->readonly_reason);
2154  trans->readonly_reason = g_strdup (reason);
2155  }
2156 }
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...
Definition: Transaction.c:1653
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1454

◆ xaccTransSetTxnType()

void xaccTransSetTxnType ( Transaction *  trans,
char  type 
)

Set the Transaction Type.

See TXN_TYPE_NONE, TXN_TYPE_INVOICE and TXN_TYPE_PAYMENT

Definition at line 2109 of file Transaction.c.

2110 {
2111  char s[2] = {type, '\0'};
2112  GValue v = G_VALUE_INIT;
2113  g_return_if_fail(trans);
2114  g_value_init (&v, G_TYPE_STRING);
2115  g_value_set_string (&v, s);
2116  xaccTransBeginEdit(trans);
2117  qof_instance_set_kvp (QOF_INSTANCE (trans), &v, 1, TRANS_TXN_TYPE_KVP);
2118  qof_instance_set_dirty(QOF_INSTANCE(trans));
2119  g_value_unset (&v);
2120  xaccTransCommitEdit(trans);
2121 }
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...
Definition: Transaction.c:1653
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1454

◆ 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 2840 of file Transaction.c.

2841 {
2842  GValue v = G_VALUE_INIT;
2843  const char *s = NULL;
2844  g_return_if_fail(trans);
2845 
2846  s = xaccTransGetVoidReason (trans);
2847  if (s == NULL) return; /* Transaction isn't voided. Bail. */
2848  xaccTransBeginEdit(trans);
2849 
2850  qof_instance_get_kvp (QOF_INSTANCE (trans), &v, 1, void_former_notes_str);
2851  if (G_VALUE_HOLDS_STRING (&v))
2852  qof_instance_set_kvp (QOF_INSTANCE (trans), &v, 1, trans_notes_str);
2853  qof_instance_set_kvp (QOF_INSTANCE (trans), NULL, 1, void_former_notes_str);
2854  qof_instance_set_kvp (QOF_INSTANCE (trans), NULL, 1, void_reason_str);
2855  qof_instance_set_kvp (QOF_INSTANCE (trans), NULL, 1, void_time_str);
2856  g_value_unset (&v);
2857  g_free (trans->void_reason);
2858  trans->void_reason = NULL;
2859 
2860  FOR_EACH_SPLIT(trans, xaccSplitUnvoid(s));
2861 
2862  /* Dirtying taken care of by ClearReadOnly */
2863  xaccTransClearReadOnly(trans);
2864  xaccTransCommitEdit(trans);
2865 }
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.
Definition: Transaction.c:2806
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...
Definition: Transaction.c:1653
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1454

◆ 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 2756 of file Transaction.c.

2757 {
2758  GValue v = G_VALUE_INIT;
2759  char iso8601_str[ISO_DATELENGTH + 1] = "";
2760 
2761  g_return_if_fail(trans && reason);
2762 
2763  /* Prevent voiding transactions that are already marked
2764  * read only, for example generated by the business features.
2765  */
2766  if (xaccTransGetReadOnly (trans))
2767  {
2768  PWARN ("Refusing to void a read-only transaction!");
2769  return;
2770  }
2771  xaccTransBeginEdit(trans);
2772  qof_instance_get_kvp (QOF_INSTANCE (trans), &v, 1, trans_notes_str);
2773  if (G_VALUE_HOLDS_STRING (&v))
2774  qof_instance_set_kvp (QOF_INSTANCE (trans), &v, 1, void_former_notes_str);
2775  else
2776  g_value_init (&v, G_TYPE_STRING);
2777 
2778  g_value_set_string (&v, _("Voided transaction"));
2779  qof_instance_set_kvp (QOF_INSTANCE (trans), &v, 1, trans_notes_str);
2780  g_value_set_string (&v, reason);
2781  qof_instance_set_kvp (QOF_INSTANCE (trans), &v, 1, void_reason_str);
2782  if (trans->void_reason != is_unset)
2783  g_free (trans->void_reason);
2784  trans->void_reason = g_strdup (reason);
2785 
2786  gnc_time64_to_iso8601_buff (gnc_time(NULL), iso8601_str);
2787  g_value_set_string (&v, iso8601_str);
2788  qof_instance_set_kvp (QOF_INSTANCE (trans), &v, 1, void_time_str);
2789  g_value_unset (&v);
2790 
2791  FOR_EACH_SPLIT(trans, xaccSplitVoid(s));
2792 
2793  /* Dirtying taken care of by SetReadOnly */
2794  xaccTransSetReadOnly(trans, _("Transaction Voided"));
2795  xaccTransCommitEdit(trans);
2796 }
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...
Definition: Transaction.c:2567
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".
Definition: Transaction.c:2139
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1653
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1454
time64 gnc_time(time64 *tbuf)
get the current local time
Definition: gnc-date.cpp:273
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:1142