GnuCash  4.2-12-g630cf65f3+
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)
 

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 * 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 tranaction 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 cannnot 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 553 of file Split.h.

◆ xaccSplitReturnGUID

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

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

◆ xaccTransGetBook

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

Definition at line 773 of file Transaction.h.

◆ xaccTransGetGUID

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

Definition at line 775 of file Transaction.h.

◆ xaccTransReturnGUID

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

Definition at line 777 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 2673 of file Transaction.c.

2674 {
2675  guint count = 0;
2676  xaccAccountTreeForEachTransaction(gnc_book_get_root_account(book),
2677  counter_thunk, (void*)&count);
2678  return count;
2679 }
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 31 of file gmock-Split.cpp.

32 {
33  g_return_val_if_fail(QOF_IS_MOCK_BOOK(book), NULL);
34  return ((QofMockBook*)book)->mallocSplit();
35 }

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

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

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

1990 {
1991  const GncGUID* guid;
1992 
1993  g_return_if_fail (split != NULL);
1994  g_return_if_fail (other_split != NULL);
1995 
1996  guid = qof_instance_get_guid (QOF_INSTANCE (other_split));
1997  xaccTransBeginEdit (split->parent);
1998  qof_instance_kvp_add_guid (QOF_INSTANCE (split), "lot-split",
1999  gnc_time(NULL), "peer_guid", guid_copy(guid));
2000  mark_split (split);
2001  qof_instance_set_dirty (QOF_INSTANCE (split));
2002  xaccTransCommitEdit (split->parent);
2003 }
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 1655 of file Split.c.

1656 {
1657  Account *aa, *ab;
1658  if (!sa && !sb) return 0;
1659  if (!sa) return -1;
1660  if (!sb) return 1;
1661 
1662  aa = sa->acc;
1663  ab = sb->acc;
1664 
1665  return g_strcmp0(xaccAccountGetCode(aa), xaccAccountGetCode(ab));
1666 }
const char * xaccAccountGetCode(const Account *acc)
Get the account's accounting code.
Definition: Account.cpp:3239
STRUCTS.

◆ xaccSplitCompareAccountFullNames()

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

Compare two splits by full name of account.

Returns similar to strcmp.

Definition at line 1634 of file Split.c.

1635 {
1636  Account *aa, *ab;
1637  char *full_a, *full_b;
1638  int retval;
1639  if (!sa && !sb) return 0;
1640  if (!sa) return -1;
1641  if (!sb) return 1;
1642 
1643  aa = sa->acc;
1644  ab = sb->acc;
1645  full_a = gnc_account_get_full_name(aa);
1646  full_b = gnc_account_get_full_name(ab);
1647  retval = g_utf8_collate(full_a, full_b);
1648  g_free(full_a);
1649  g_free(full_b);
1650  return retval;
1651 }
STRUCTS.
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:3191

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

1691 {
1692  const char *ca, *cb;
1693  if (!sa && !sb) return 0;
1694  if (!sa) return -1;
1695  if (!sb) return 1;
1696 
1697  ca = xaccSplitGetCorrAccountCode(sa);
1698  cb = xaccSplitGetCorrAccountCode(sb);
1699  return g_strcmp0(ca, cb);
1700 }
const char * xaccSplitGetCorrAccountCode(const Split *sa)
document me
Definition: Split.c:1617

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

1670 {
1671  char *ca, *cb;
1672  int retval;
1673  if (!sa && !sb) return 0;
1674  if (!sa) return -1;
1675  if (!sb) return 1;
1676 
1677  /* doesn't matter what separator we use
1678  * as long as they are the same
1679  */
1680 
1683  retval = g_strcmp0(ca, cb);
1684  g_free(ca);
1685  g_free(cb);
1686  return retval;
1687 }
char * xaccSplitGetCorrAccountFullName(const Split *sa)
These functions take a split, get the corresponding split on the "other side" of the transaction...
Definition: Split.c:1601

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

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

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

1453 {
1454  Account *acc;
1455  Transaction *trans;
1456  GncEventData ed;
1457 
1458  if (!split) return TRUE;
1459 
1460  acc = split->acc;
1461  trans = split->parent;
1462  if (acc && !qof_instance_get_destroying(acc)
1463  && !qof_instance_get_destroying(trans)
1464  && xaccTransGetReadOnly(trans))
1465  return FALSE;
1466 
1467  xaccTransBeginEdit(trans);
1468  ed.node = split;
1469  ed.idx = xaccTransGetSplitIndex(trans, split);
1470  qof_instance_set_dirty(QOF_INSTANCE(split));
1471  qof_instance_set_destroying(split, TRUE);
1472  qof_event_gen(&trans->inst, GNC_EVENT_ITEM_REMOVED, &ed);
1473  xaccTransCommitEdit(trans);
1474 
1475  return TRUE;
1476 }
STRUCTS.
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:2487
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:2236
void qof_event_gen(QofInstance *entity, QofEventId event_id, gpointer event_data)
Invoke all registered event handlers using the given arguments.
Definition: qofevent.cpp:234

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

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

◆ xaccSplitGetAccount()

Account* xaccSplitGetAccount ( const Split *  split)

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

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

46 {
47  g_return_val_if_fail(GNC_IS_MOCK_SPLIT(split), NULL);
48  return ((MockSplit*)split)->getAccount();
49 }

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

117 {
118  g_return_val_if_fail(GNC_IS_MOCK_SPLIT(split), NULL);
119  return ((MockSplit*)split)->getAction();
120 }

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

61 {
62  g_return_val_if_fail(GNC_IS_MOCK_SPLIT(split), gnc_numeric_zero());
63  return ((MockSplit*)split)->getAmount();
64 }

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

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

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

1357 {
1358  if (!s || !s->acc || !s->parent) return gnc_numeric_zero();
1359 
1360  /* be more precise -- the value depends on the currency we want it
1361  * expressed in. */
1362  if (gnc_commodity_equiv(xaccTransGetCurrency(s->parent), base_currency))
1363  return xaccSplitGetValue(s);
1364  if (gnc_commodity_equiv(xaccAccountGetCommodity(s->acc), base_currency))
1365  return xaccSplitGetAmount(s);
1366 
1367  PERR ("inappropriate base currency %s "
1368  "given split currency=%s and commodity=%s\n",
1369  gnc_commodity_get_printname(base_currency),
1372  return gnc_numeric_zero();
1373 }
#define PERR(format, args...)
Log a serious error.
Definition: qoflog.h:246
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:1903
gnc_commodity * xaccAccountGetCommodity(const Account *acc)
Get the account's commodity.
Definition: Account.cpp:3307
gnc_commodity * xaccTransGetCurrency(const Transaction *trans)
Returns the valuation commodity of this transaction.
Definition: Transaction.c:1356
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:1897

◆ xaccSplitGetBook()

QofBook* xaccSplitGetBook ( const Split *  split)

Returns the book of this split, i.e.

the entity where this split is stored.

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

39 {
40  g_return_val_if_fail(GNC_IS_MOCK_SPLIT(split), NULL);
41  return ((MockSplit*)split)->getBook();
42 }

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

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

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

1602 {
1603  static const char *split_const = NULL;
1604  const Split *other_split;
1605 
1606  if (!get_corr_account_split(sa, &other_split))
1607  {
1608  if (!split_const)
1609  split_const = _("-- Split Transaction --");
1610 
1611  return g_strdup(split_const);
1612  }
1613  return gnc_account_get_full_name(other_split->acc);
1614 }
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:3191

◆ xaccSplitGetDateReconciled()

time64 xaccSplitGetDateReconciled ( const Split *  split)

Retrieve the date when the Split was reconciled.

Definition at line 1802 of file Split.c.

1803 {
1804  return split ? split->date_reconciled : 0;
1805 }

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

1864 {
1865  return split ? split->lot : NULL;
1866 }

◆ xaccSplitGetMemo()

const char* xaccSplitGetMemo ( const Split *  split)

Returns the memo string.

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

89 {
90  g_return_val_if_fail(GNC_IS_MOCK_SPLIT(split), NULL);
91  return ((MockSplit*)split)->getMemo();
92 }

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

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

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

124 {
125  g_return_val_if_fail(GNC_IS_MOCK_SPLIT(split), NULL);
126  return ((MockSplit*)split)->getOtherSplit();
127 }

◆ xaccSplitGetParent()

Transaction* xaccSplitGetParent ( const Split *  split)

Returns the parent transaction of the split.

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

131 {
132  g_return_val_if_fail(GNC_IS_MOCK_SPLIT(split), NULL);
133  return ((MockSplit*)split)->getParent();
134 }

◆ xaccSplitGetReconcile()

char xaccSplitGetReconcile ( const Split *  split)

Returns the value of the reconcile flag.

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

96 {
97  g_return_val_if_fail(GNC_IS_MOCK_SPLIT(split), VREC);
98  return ((MockSplit*)split)->getReconcile();
99 }
#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 1295 of file Split.c.

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

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

1910 {
1911  gnc_numeric amt, val, price;
1912  if (!split) return gnc_numeric_create(1, 1);
1913 
1914 
1915  /* if amount == 0 and value == 0, then return 1.
1916  * if amount == 0 and value != 0 then return 0.
1917  * otherwise return value/amount
1918  */
1919 
1920  amt = xaccSplitGetAmount(split);
1921  val = xaccSplitGetValue(split);
1922  if (gnc_numeric_zero_p(amt))
1923  {
1924  if (gnc_numeric_zero_p(val))
1925  return gnc_numeric_create(1, 1);
1926  return gnc_numeric_create(0, 1);
1927  }
1928  price = gnc_numeric_div(val, amt,
1931 
1932  /* During random checks we can get some very weird prices. Let's
1933  * handle some overflow and other error conditions by returning
1934  * zero. But still print an error to let us know it happened.
1935  */
1936  if (gnc_numeric_check(price))
1937  {
1938  PERR("Computing share price failed (%d): [ %" G_GINT64_FORMAT " / %"
1939  G_GINT64_FORMAT " ] / [ %" G_GINT64_FORMAT " / %" G_GINT64_FORMAT " ]",
1940  gnc_numeric_check(price), val.num, val.denom, amt.num, amt.denom);
1941  return gnc_numeric_create(0, 1);
1942  }
1943 
1944  return price;
1945 }
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:246
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:1903
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:1897

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

1958 {
1959  GValue v = G_VALUE_INIT;
1960  const char *split_type = NULL;
1961 
1962  if (!s) return NULL;
1963  qof_instance_get_kvp (QOF_INSTANCE (s), &v, 1, "split-type");
1964  if (G_VALUE_HOLDS_STRING (&v))
1965  split_type = g_value_get_string (&v);
1966  return split_type ? split_type : "normal";
1967 }
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 74 of file gmock-Split.cpp.

75 {
76  g_return_val_if_fail(GNC_IS_MOCK_SPLIT(split), gnc_numeric_zero());
77  return ((MockSplit*)split)->getValue();
78 }

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

2013 {
2014  const GncGUID* guid;
2015 
2016  g_return_val_if_fail (split != NULL, FALSE);
2017  g_return_val_if_fail (other_split != NULL, FALSE);
2018 
2019  guid = qof_instance_get_guid (QOF_INSTANCE (other_split));
2020  return qof_instance_kvp_has_guid (QOF_INSTANCE (split), "lot-split",
2021  "peer_guid", guid);
2022 }
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 1055 of file Split.c.

1056 {
1057  QofCollection *col;
1058  if (!guid || !book) return NULL;
1059  col = qof_book_get_collection (book, GNC_ID_SPLIT);
1060  return (Split *) qof_collection_lookup_entity (col, guid);
1061 }
QofInstance * qof_collection_lookup_entity(const QofCollection *col, const GncGUID *guid)
Find the entity going only from its guid.
Definition: qofid.cpp:214
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 1972 of file Split.c.

1973 {
1974  GValue v = G_VALUE_INIT;
1975  xaccTransBeginEdit (s->parent);
1976 
1977  s->value = gnc_numeric_zero();
1978  g_value_init (&v, G_TYPE_STRING);
1979  g_value_set_string (&v, "stock-split");
1980  qof_instance_set_kvp (QOF_INSTANCE (s), &v, 1, "split-type");
1981  SET_GAINS_VDIRTY(s);
1982  mark_split(s);
1983  qof_instance_set_dirty(QOF_INSTANCE(s));
1984  xaccTransCommitEdit(s->parent);
1985 }
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 2042 of file Split.c.

2043 {
2044  xaccTransBeginEdit (split->parent);
2045  qof_instance_kvp_merge_guids (QOF_INSTANCE (split),
2046  QOF_INSTANCE (other_split), "lot-split");
2047  mark_split (split);
2048  qof_instance_set_dirty (QOF_INSTANCE (split));
2049  xaccTransCommitEdit (split->parent);
2050 }
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 1482 of file Split.c.

1483 {
1484  int retval;
1485  int comp;
1486  char *da, *db;
1487  gboolean action_for_num;
1488 
1489  if (sa == sb) return 0;
1490  /* nothing is always less than something */
1491  if (!sa) return -1;
1492  if (!sb) return +1;
1493 
1494  /* sort in transaction order, but use split action rather than trans num
1495  * according to book option */
1497  (xaccSplitGetBook (sa));
1498  if (action_for_num)
1499  retval = xaccTransOrder_num_action (sa->parent, sa->action,
1500  sb->parent, sb->action);
1501  else
1502  retval = xaccTransOrder (sa->parent, sb->parent);
1503  if (retval) return retval;
1504 
1505  /* otherwise, sort on memo strings */
1506  da = sa->memo ? sa->memo : "";
1507  db = sb->memo ? sb->memo : "";
1508  retval = g_utf8_collate (da, db);
1509  if (retval)
1510  return retval;
1511 
1512  /* otherwise, sort on action strings */
1513  da = sa->action ? sa->action : "";
1514  db = sb->action ? sb->action : "";
1515  retval = g_utf8_collate (da, db);
1516  if (retval != 0)
1517  return retval;
1518 
1519  /* the reconciled flag ... */
1520  if (sa->reconciled < sb->reconciled) return -1;
1521  if (sa->reconciled > sb->reconciled) return +1;
1522 
1523  /* compare amounts */
1525  if (comp < 0) return -1;
1526  if (comp > 0) return +1;
1527 
1529  if (comp < 0) return -1;
1530  if (comp > 0) return +1;
1531 
1532  /* if dates differ, return */
1533  if (sa->date_reconciled < sb->date_reconciled)
1534  return -1;
1535  else if (sa->date_reconciled > sb->date_reconciled)
1536  return 1;
1537 
1538  /* else, sort on guid - keeps sort stable. */
1539  retval = qof_instance_guid_compare(sa, sb);
1540  if (retval) return retval;
1541 
1542  return 0;
1543 }
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:1951
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:1889
gnc_numeric xaccSplitGetValue(const Split *split)
Returns the value of this split in the transaction&#39;s commodity.
Definition: Split.c:1903
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:1883
gnc_numeric xaccSplitGetAmount(const Split *split)
Returns the amount of the split in the account&#39;s commodity.
Definition: Split.c:1897

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

2026 {
2027  const GncGUID* guid;
2028 
2029  g_return_if_fail (split != NULL);
2030  g_return_if_fail (other_split != NULL);
2031 
2032  guid = qof_instance_get_guid (QOF_INSTANCE (other_split));
2033  xaccTransBeginEdit (split->parent);
2034  qof_instance_kvp_remove_guid (QOF_INSTANCE (split), "lot-split",
2035  "peer_guid", guid);
2036  mark_split (split);
2037  qof_instance_set_dirty (QOF_INSTANCE (split));
2038  xaccTransCommitEdit (split->parent);
2039 }
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 1729 of file Split.c.

1730 {
1731  if (!split || !actn) return;
1732  xaccTransBeginEdit (split->parent);
1733 
1734  CACHE_REPLACE(split->action, actn);
1735  qof_instance_set_dirty(QOF_INSTANCE(split));
1736  xaccTransCommitEdit(split->parent);
1737 
1738 }
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 67 of file gmock-Split.cpp.

68 {
69  g_return_if_fail(GNC_IS_MOCK_SPLIT(split));
70  ((MockSplit*)split)->setAmount(amt);
71 }

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

1303 {
1304  const gnc_commodity *currency;
1305  const gnc_commodity *commodity;
1306 
1307  if (!s) return;
1308  xaccTransBeginEdit (s->parent);
1309 
1310  if (!s->acc)
1311  {
1312  PERR ("split must have a parent account");
1313  return;
1314  }
1315 
1316  currency = xaccTransGetCurrency (s->parent);
1317  commodity = xaccAccountGetCommodity (s->acc);
1318 
1319  /* If the base_currency is the transaction's commodity ('currency'),
1320  * set the value. If it's the account commodity, set the
1321  * amount. If both, set both. */
1322  if (gnc_commodity_equiv(currency, base_currency))
1323  {
1324  if (gnc_commodity_equiv(commodity, base_currency))
1325  {
1326  s->amount = gnc_numeric_convert(value,
1327  get_commodity_denom(s),
1329  }
1330  s->value = gnc_numeric_convert(value,
1331  get_currency_denom(s),
1333  }
1334  else if (gnc_commodity_equiv(commodity, base_currency))
1335  {
1336  s->amount = gnc_numeric_convert(value, get_commodity_denom(s),
1338  }
1339  else
1340  {
1341  PERR ("inappropriate base currency %s "
1342  "given split currency=%s and commodity=%s\n",
1343  gnc_commodity_get_printname(base_currency),
1344  gnc_commodity_get_printname(currency),
1345  gnc_commodity_get_printname(commodity));
1346  return;
1347  }
1348 
1349  SET_GAINS_A_VDIRTY(s);
1350  mark_split (s);
1351  qof_instance_set_dirty(QOF_INSTANCE(s));
1352  xaccTransCommitEdit(s->parent);
1353 }
#define PERR(format, args...)
Log a serious error.
Definition: qoflog.h:246
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:3307
gnc_commodity * xaccTransGetCurrency(const Transaction *trans)
Returns the valuation commodity of this transaction.
Definition: Transaction.c:1356
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 109 of file gmock-Split.cpp.

110 {
111  g_return_if_fail(GNC_IS_MOCK_SPLIT(split));
112  ((MockSplit*)split)->setDateReconciledSecs(secs);
113 }

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

1711 {
1712  if (!split || !memo) return;
1713  xaccTransBeginEdit (split->parent);
1714 
1715  CACHE_REPLACE(split->memo, memo);
1716  qof_instance_set_dirty(QOF_INSTANCE(split));
1717  xaccTransCommitEdit(split->parent);
1718 
1719 }
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 102 of file gmock-Split.cpp.

103 {
104  g_return_if_fail(GNC_IS_MOCK_SPLIT(split));
105  ((MockSplit*)split)->setReconcile(recn);
106 }

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

1179 {
1180  if (!s) return;
1181  ENTER (" ");
1182  xaccTransBeginEdit (s->parent);
1183 
1184  s->value = gnc_numeric_mul(xaccSplitGetAmount(s),
1185  price, get_currency_denom(s),
1187 
1188  SET_GAINS_VDIRTY(s);
1189  mark_split (s);
1190  qof_instance_set_dirty(QOF_INSTANCE(s));
1191  xaccTransCommitEdit(s->parent);
1192  LEAVE ("");
1193 }
#define ENTER(format, args...)
Print a function entry debugging message.
Definition: qoflog.h:270
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:280
gnc_numeric xaccSplitGetAmount(const Split *split)
Returns the amount of the split in the account&#39;s commodity.
Definition: Split.c:1897

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

1151 {
1152  if (!s) return;
1153  ENTER (" ");
1154  xaccTransBeginEdit (s->parent);
1155 
1156  s->amount = gnc_numeric_convert(amt, get_commodity_denom(s),
1158  s->value = gnc_numeric_mul(s->amount, price,
1159  get_currency_denom(s), GNC_HOW_RND_ROUND_HALF_UP);
1160 
1161  SET_GAINS_A_VDIRTY(s);
1162  mark_split (s);
1163  qof_instance_set_dirty(QOF_INSTANCE(s));
1164  xaccTransCommitEdit(s->parent);
1165  LEAVE ("");
1166 }
#define ENTER(format, args...)
Print a function entry debugging message.
Definition: qoflog.h:270
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:280

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

82 {
83  g_return_if_fail(GNC_IS_MOCK_SPLIT(split));
84  ((MockSplit*)split)->setValue(val);
85 }

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

2113 {
2114  GValue v = G_VALUE_INIT;
2115  gnc_numeric *num = NULL;
2116  g_return_val_if_fail(split, gnc_numeric_zero());
2117  qof_instance_get_kvp (QOF_INSTANCE (split), &v, 1, void_former_amt_str);
2118  if (G_VALUE_HOLDS_BOXED (&v))
2119  num = (gnc_numeric*)g_value_get_boxed (&v);
2120  return num ? *num : gnc_numeric_zero();
2121 }
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 2124 of file Split.c.

2125 {
2126  GValue v = G_VALUE_INIT;
2127  gnc_numeric *num = NULL;
2128  g_return_val_if_fail(split, gnc_numeric_zero());
2129  qof_instance_get_kvp (QOF_INSTANCE (split), &v, 1, void_former_val_str);
2130  if (G_VALUE_HOLDS_BOXED (&v))
2131  num = (gnc_numeric*)g_value_get_boxed (&v);
2132  return num ? *num : gnc_numeric_zero();
2133 }
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 29 of file gmock-Transaction.cpp.

30 {
31  g_return_if_fail(GNC_IS_MOCK_TRANSACTION(trans));
32  ((MockTransaction*)trans)->beginEdit();
33 }

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

37 {
38  g_return_if_fail(GNC_IS_MOCK_TRANSACTION(trans));
39  ((MockTransaction*)trans)->commitEdit();
40 }

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

751 {
752  gboolean change_accounts = FALSE;
753  GList *node;
754 
755  if (!from_trans || !to_trans)
756  return;
757 
758  change_accounts = from_acc && GNC_IS_ACCOUNT(to_acc) && from_acc != to_acc;
759  xaccTransBeginEdit(to_trans);
760 
761  FOR_EACH_SPLIT(to_trans, xaccSplitDestroy(s));
762  g_list_free(to_trans->splits);
763  to_trans->splits = NULL;
764 
765  xaccTransSetCurrency(to_trans, xaccTransGetCurrency(from_trans));
766  xaccTransSetDescription(to_trans, xaccTransGetDescription(from_trans));
767 
768  if ((xaccTransGetNum(to_trans) == NULL) || (g_strcmp0 (xaccTransGetNum(to_trans), "") == 0))
769  xaccTransSetNum(to_trans, xaccTransGetNum(from_trans));
770 
771  xaccTransSetNotes(to_trans, xaccTransGetNotes(from_trans));
772  xaccTransSetDocLink(to_trans, xaccTransGetDocLink (from_trans));
773  if(!no_date)
774  {
775  xaccTransSetDatePostedSecs(to_trans, xaccTransRetDatePosted (from_trans));
776  }
777 
778  /* Each new split will be parented to 'to' */
779  for (node = from_trans->splits; node; node = node->next)
780  {
781  Split *new_split = xaccMallocSplit( qof_instance_get_book(QOF_INSTANCE(from_trans)));
782  xaccSplitCopyOnto(node->data, new_split);
783  if (change_accounts && xaccSplitGetAccount(node->data) == from_acc)
784  xaccSplitSetAccount(new_split, to_acc);
785  xaccSplitSetParent(new_split, to_trans);
786  }
787  xaccTransCommitEdit(to_trans);
788 }
QofBook * qof_instance_get_book(gconstpointer inst)
Return the book pointer.
gboolean xaccSplitDestroy(Split *split)
Destructor.
Definition: Split.c:1452
void xaccTransSetNotes(Transaction *trans, const char *notes)
Sets the transaction Notes.
Definition: Transaction.c:2185
void xaccSplitCopyOnto(const Split *from_split, Split *to_split)
This is really a helper for xaccTransCopyOnto.
Definition: Split.c:634
void xaccTransSetDescription(Transaction *trans, const char *desc)
Sets the transaction Description.
Definition: Transaction.c:2148
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:2128
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:2338
const char * xaccTransGetDocLink(const Transaction *trans)
Gets the transaction Document Link.
Definition: Transaction.c:2350
void xaccTransSetCurrency(Transaction *trans, gnc_commodity *curr)
Set a new currency on a transaction.
Definition: Transaction.c:1415
const char * xaccTransGetNotes(const Transaction *trans)
Gets the transaction Notes.
Definition: Transaction.c:2361
time64 xaccTransRetDatePosted(const Transaction *trans)
Retrieve the posted date of the transaction.
Definition: Transaction.c:2408
const char * xaccTransGetDescription(const Transaction *trans)
Gets the transaction Description.
Definition: Transaction.c:2344
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1643
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1444
Split * xaccMallocSplit(QofBook *book)
Constructor.
Definition: gmock-Split.cpp:31
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:1977
Account * xaccSplitGetAccount(const Split *split)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: gmock-Split.cpp:45
gnc_commodity * xaccTransGetCurrency(const Transaction *trans)
Returns the valuation commodity of this transaction.
Definition: Transaction.c:1356
void xaccTransSetDocLink(Transaction *trans, const char *doclink)
Sets the transaction Document Link.
Definition: Transaction.c:2159

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

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

◆ xaccTransCountSplits()

int xaccTransCountSplits ( const Transaction *  trans)

Returns the number of splits in this transaction.

Definition at line 2329 of file Transaction.c.

2330 {
2331  gint i = 0;
2332  g_return_val_if_fail (trans != NULL, 0);
2333  FOR_EACH_SPLIT(trans, i++);
2334  return i;
2335 }

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

129 {
130  g_return_if_fail(GNC_IS_MOCK_TRANSACTION(trans));
131  ((MockTransaction*)trans)->destroy();
132 }

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

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

1195 {
1196  gnc_numeric total = gnc_numeric_zero ();
1197  if (!trans || !acc) return total;
1198 
1199  total = gnc_numeric_convert (total, xaccAccountGetCommoditySCU (acc),
1201  FOR_EACH_SPLIT(trans, if (acc == xaccSplitGetAccount(s))
1202  total = gnc_numeric_add_fixed(
1203  total, xaccSplitGetAmount(s)));
1204  return total;
1205 }
int xaccAccountGetCommoditySCU(const Account *acc)
Return the SCU for the account.
Definition: Account.cpp:2608
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:45
gnc_numeric xaccSplitGetAmount(const Split *split)
Returns the amount of the split in the account&#39;s commodity.
Definition: gmock-Split.cpp:60

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

1320 {
1321  GList *node;
1322  Split *last_split = NULL;
1323 
1324  // Not really the appropriate error value.
1325  g_return_val_if_fail(account && trans, gnc_numeric_error(GNC_ERROR_ARG));
1326 
1327  for (node = trans->splits; node; node = node->next)
1328  {
1329  Split *split = node->data;
1330 
1331  if (!xaccTransStillHasSplit(trans, split))
1332  continue;
1333  if (xaccSplitGetAccount(split) != account)
1334  continue;
1335 
1336  if (!last_split)
1337  {
1338  last_split = split;
1339  continue;
1340  }
1341 
1342  /* This test needs to correspond to the comparison function used when
1343  sorting the splits for computing the running balance. */
1344  if (xaccSplitOrder (last_split, split) < 0)
1345  last_split = split;
1346  }
1347 
1348  return xaccSplitGetBalance (last_split);
1349 }
gint xaccSplitOrder(const Split *sa, const Split *sb)
The xaccSplitOrder(sa,sb) method is useful for sorting.
Definition: Split.c:1482
gnc_numeric xaccSplitGetBalance(const Split *s)
Returns the running balance up to and including the indicated split.
Definition: Split.c:1277
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:45

◆ 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 convienience to view everything at once.

Definition at line 1178 of file Transaction.c.

1180 {
1181  gnc_numeric total = gnc_numeric_zero ();
1182  if (!trans || !acc) return total;
1183 
1184  FOR_EACH_SPLIT(trans, if (acc == xaccSplitGetAccount(s))
1185 {
1186  total = gnc_numeric_add (total, xaccSplitGetValue (s),
1189  });
1190  return total;
1191 }
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:74
Account * xaccSplitGetAccount(const Split *split)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: gmock-Split.cpp:45
#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 2266 of file Transaction.c.

2267 {
2268  GList *apar_splits = NULL;
2269  if (!trans) return NULL;
2270 
2271  FOR_EACH_SPLIT (trans,
2272  const Account *account = xaccSplitGetAccount(s);
2273  if (account && xaccAccountIsAPARType(xaccAccountGetType(account)))
2274  {
2275 
2276  if (!strict)
2277  apar_splits = g_list_prepend (apar_splits, s);
2278  else
2279  {
2280  GncOwner owner;
2281  GNCLot *lot = xaccSplitGetLot(s);
2282  if (lot &&
2283  (gncInvoiceGetInvoiceFromLot (lot) ||
2284  gncOwnerGetOwnerFromLot (lot, &owner)))
2285  apar_splits = g_list_prepend (apar_splits, s);
2286  }
2287  }
2288  );
2289 
2290  apar_splits = g_list_reverse (apar_splits);
2291  return apar_splits;
2292 }
GNCAccountType xaccAccountGetType(const Account *acc)
Returns the account&#39;s account type.
Definition: Account.cpp:3162
STRUCTS.
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:4485
GncInvoice * gncInvoiceGetInvoiceFromLot(GNCLot *lot)
Given a LOT, find and return the Invoice attached to the lot.
Definition: gncInvoice.c:1273
Account * xaccSplitGetAccount(const Split *split)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: gmock-Split.cpp:45
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:1863

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

1357 {
1358  return trans ? trans->common_currency : NULL;
1359 }

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

66 {
67  g_return_val_if_fail(GNC_IS_MOCK_TRANSACTION(trans), 0);
68  return ((MockTransaction*)trans)->getDate();
69 }

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

2402 {
2403  return trans ? trans->date_entered : 0;
2404 }

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

2415 {
2416  GDate result;
2417  g_date_clear (&result, 1);
2418  if (trans)
2419  {
2420  /* Can we look up this value in the kvp slot? If yes, use it
2421  * from there because it doesn't suffer from time zone
2422  * shifts. */
2423  GValue v = G_VALUE_INIT;
2424  qof_instance_get_kvp (QOF_INSTANCE (trans), &v, 1, TRANS_DATE_POSTED);
2425  if (G_VALUE_HOLDS_BOXED (&v))
2426  result = *(GDate*)g_value_get_boxed (&v);
2427  if (! g_date_valid (&result) || gdate_to_time64 (result) == INT64_MAX)
2428  {
2429  /* Well, this txn doesn't have a valid GDate saved in a slot.
2430  * time64_to_gdate() uses local time and we want UTC so we have
2431  * to write it out.
2432  */
2433  time64 time = xaccTransGetDate(trans);
2434  struct tm *stm = gnc_gmtime(&time);
2435  if (stm)
2436  {
2437  g_date_set_dmy(&result, stm->tm_mday,
2438  (GDateMonth)(stm->tm_mon + 1),
2439  stm->tm_year + 1900);
2440  free(stm);
2441  }
2442  }
2443  }
2444  return result;
2445 }
time64 xaccTransGetDate(const Transaction *trans)
Retrieve the posted date of the transaction.
Definition: Transaction.c:2394
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:84

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

2306 {
2307  FOR_EACH_SPLIT (trans,
2308  const Account *account = xaccSplitGetAccount(s);
2309  if (account && xaccAccountIsAPARType(xaccAccountGetType(account)))
2310  {
2311  GNCLot *lot;
2312  GncOwner owner;
2313 
2314  if (!strict)
2315  return s;
2316 
2317  lot = xaccSplitGetLot(s);
2318  if (lot &&
2319  (gncInvoiceGetInvoiceFromLot (lot) ||
2320  gncOwnerGetOwnerFromLot (lot, &owner)))
2321  return s;
2322  }
2323  );
2324 
2325  return NULL;
2326 }
GNCAccountType xaccAccountGetType(const Account *acc)
Returns the account&#39;s account type.
Definition: Account.cpp:3162
STRUCTS.
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:4485
GncInvoice * gncInvoiceGetInvoiceFromLot(GNCLot *lot)
Given a LOT, find and return the Invoice attached to the lot.
Definition: gncInvoice.c:1273
Account * xaccSplitGetAccount(const Split *split)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: gmock-Split.cpp:45
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:1863

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

2295 {
2296  FOR_EACH_SPLIT (trans,
2297  const Account *account = xaccSplitGetAccount(s);
2298  if (account && gncBusinessIsPaymentAcctType(xaccAccountGetType(account)))
2299  return s;
2300  );
2301 
2302  return NULL;
2303 }
GNCAccountType xaccAccountGetType(const Account *acc)
Returns the account&#39;s account type.
Definition: Account.cpp:3162
STRUCTS.
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:45

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

1061 {
1062  /* imbal_value is used if either (1) the transaction has a non currency
1063  split or (2) all the splits are in the same currency. If there are
1064  no non-currency splits and not all splits are in the same currency then
1065  imbal_list is used to compute the imbalance. */
1066  MonetaryList *imbal_list = NULL;
1067  gnc_numeric imbal_value = gnc_numeric_zero();
1068  gboolean trading_accts;
1069 
1070  if (!trans) return imbal_list;
1071 
1072  ENTER("(trans=%p)", trans);
1073 
1074  trading_accts = xaccTransUseTradingAccounts (trans);
1075 
1076  /* If using trading accounts and there is at least one split that is not
1077  in the transaction currency or a split that has a price or exchange
1078  rate other than 1, then compute the balance in each commodity in the
1079  transaction. Otherwise (all splits are in the transaction's currency)
1080  then compute the balance using the value fields.
1081 
1082  Optimize for the common case of only one currency and a balanced
1083  transaction. */
1084  FOR_EACH_SPLIT(trans,
1085  {
1086  gnc_commodity *commodity;
1088  if (trading_accts &&
1089  (imbal_list ||
1090  ! gnc_commodity_equiv(commodity, trans->common_currency) ||
1092  {
1093  /* Need to use (or already are using) a list of imbalances in each of
1094  the currencies used in the transaction. */
1095  if (! imbal_list)
1096  {
1097  /* All previous splits have been in the transaction's common
1098  currency, so imbal_value is in this currency. */
1099  imbal_list = gnc_monetary_list_add_value(imbal_list,
1100  trans->common_currency,
1101  imbal_value);
1102  }
1103  imbal_list = gnc_monetary_list_add_value(imbal_list, commodity,
1104  xaccSplitGetAmount(s));
1105  }
1106 
1107  /* Add it to the value accumulator in case we need it. */
1108  imbal_value = gnc_numeric_add(imbal_value, xaccSplitGetValue(s),
1110  } );
1111 
1112 
1113  if (!imbal_list && !gnc_numeric_zero_p(imbal_value))
1114  {
1115  /* Not balanced and no list, create one. If we found multiple currencies
1116  and no non-currency commodity then imbal_list will already exist and
1117  we won't get here. */
1118  imbal_list = gnc_monetary_list_add_value(imbal_list,
1119  trans->common_currency,
1120  imbal_value);
1121  }
1122 
1123  /* Delete all the zero entries from the list, perhaps leaving an
1124  empty list */
1125  imbal_list = gnc_monetary_list_delete_zeros(imbal_list);
1126 
1127  LEAVE("(trans=%p), imbal=%p", trans, imbal_list);
1128  return imbal_list;
1129 }
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:1023
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:270
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:74
Account * xaccSplitGetAccount(const Split *split)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: gmock-Split.cpp:45
gnc_commodity * xaccAccountGetCommodity(const Account *acc)
Get the account&#39;s commodity.
Definition: Account.cpp:3307
#define LEAVE(format, args...)
Print a function exit debugging message.
Definition: qoflog.h:280
#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:60

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

108 {
109  g_return_val_if_fail(GNC_IS_MOCK_TRANSACTION(trans), gnc_numeric_zero());
110  return ((MockTransaction*)trans)->getImbalanceValue();
111 }

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

94 {
95  g_return_val_if_fail(GNC_IS_MOCK_TRANSACTION(trans), NULL);
96  return ((MockTransaction*)trans)->getNotes();
97 }

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

2253 {
2254  GList *pay_splits = NULL;
2255  FOR_EACH_SPLIT (trans,
2256  const Account *account = xaccSplitGetAccount(s);
2257  if (account && gncBusinessIsPaymentAcctType(xaccAccountGetType(account)))
2258  pay_splits = g_list_prepend (pay_splits, s);
2259  );
2260 
2261  pay_splits = g_list_reverse (pay_splits);
2262  return pay_splits;
2263 }
GNCAccountType xaccAccountGetType(const Account *acc)
Returns the account&#39;s account type.
Definition: Account.cpp:3162
STRUCTS.
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:45

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

2488 {
2489  if (!trans)
2490  return NULL;
2491 
2492  if (!trans->reason_cache_valid)
2493  {
2494  GValue v = G_VALUE_INIT;
2495  qof_instance_get_kvp (QOF_INSTANCE(trans), &v, 1, TRANS_READ_ONLY_REASON);
2496 
2497  /* Clear possible old cache value first */
2498  g_free (trans->readonly_reason);
2499  trans->readonly_reason = NULL;
2500 
2501  /* Then set the new one */
2502  if (G_VALUE_HOLDS_STRING (&v))
2503  {
2504  trans->readonly_reason = g_value_dup_string (&v);
2505  g_value_unset (&v);
2506  }
2507  trans->reason_cache_valid = TRUE;
2508  }
2509  return trans->readonly_reason;
2510 }
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 2823 of file Transaction.c.

2824 {
2825  GValue v = G_VALUE_INIT;
2826  g_return_val_if_fail(trans, NULL);
2827  qof_instance_get_kvp (QOF_INSTANCE(trans), &v, 1, TRANS_REVERSED_BY);
2828  if (G_VALUE_HOLDS_BOXED (&v))
2829  return xaccTransLookup((GncGUID*)g_value_get_boxed (&v),
2830  qof_instance_get_book(trans));
2831  return NULL;
2832 }
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:1032
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 43 of file gmock-Transaction.cpp.

44 {
45  g_return_val_if_fail(GNC_IS_MOCK_TRANSACTION(trans), NULL);
46  return ((MockTransaction*)trans)->getSplit(i);
47 }

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

51 {
52  g_return_val_if_fail(GNC_IS_MOCK_TRANSACTION(trans), NULL);
53  return trans ? ((MockTransaction*)trans)->getSplitList() : NULL;
54 }

◆ xaccTransGetTxnType()

char xaccTransGetTxnType ( const Transaction *  trans)

Returns the Transaction Type.

See TXN_TYPE_NONE, TXN_TYPE_INVOICE and TXN_TYPE_PAYMENT

Definition at line 2471 of file Transaction.c.

2472 {
2473  const char *s = NULL;
2474  GValue v = G_VALUE_INIT;
2475 
2476  if (!trans) return TXN_TYPE_NONE;
2477  qof_instance_get_kvp (QOF_INSTANCE (trans), &v, 1, TRANS_TXN_TYPE_KVP);
2478  if (G_VALUE_HOLDS_STRING (&v))
2479  s = g_value_get_string (&v);
2480  if (s && strlen (s) == 1)
2481  return *s;
2482 
2483  return TXN_TYPE_NONE;
2484 }
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:123

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

2738 {
2739  GValue v = G_VALUE_INIT;
2740  g_return_val_if_fail(trans, FALSE);
2741 
2742  qof_instance_get_kvp (QOF_INSTANCE (trans), &v, 1, void_reason_str);
2743  if (G_VALUE_HOLDS_STRING (&v))
2744  return g_value_get_string (&v);
2745  return NULL;
2746 }
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 2724 of file Transaction.c.

2725 {
2726  const char *s = NULL;
2727  GValue v = G_VALUE_INIT;
2728  g_return_val_if_fail(trans, FALSE);
2729 
2730  qof_instance_get_kvp (QOF_INSTANCE (trans), &v, 1, void_reason_str);
2731  if (G_VALUE_HOLDS_STRING (&v))
2732  s = g_value_get_string (&v);
2733  return s && strlen(s);
2734 }
void qof_instance_get_kvp(QofInstance *, GValue *value, unsigned count,...)
Retrieves the contents of a KVP slot into a provided GValue.

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

2750 {
2751  GValue v = G_VALUE_INIT;
2752  const char *s = NULL;
2753  time64 void_time = 0;
2754 
2755  g_return_val_if_fail(tr, void_time);
2756  qof_instance_get_kvp (QOF_INSTANCE (tr), &v, 1, void_time_str);
2757  if (G_VALUE_HOLDS_STRING (&v))
2758  s = g_value_get_string (&v);
2759  if (s)
2760  return gnc_iso8601_to_time64_gmt (s);
2761  return void_time;
2762 }
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:84

◆ xaccTransIsBalanced()

gboolean xaccTransIsBalanced ( const Transaction *  trans)

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

Definition at line 1132 of file Transaction.c.

1133 {
1134  MonetaryList *imbal_list;
1135  gboolean result;
1136  gnc_numeric imbal = gnc_numeric_zero();
1137  gnc_numeric imbal_trading = gnc_numeric_zero();
1138 
1139  if (trans == NULL) return FALSE;
1140 
1141  if (xaccTransUseTradingAccounts(trans))
1142  {
1143  /* Transaction is imbalanced if the value is imbalanced in either
1144  trading or non-trading splits. One can't be used to balance
1145  the other. */
1146  FOR_EACH_SPLIT(trans,
1147  {
1148  Account *acc = xaccSplitGetAccount(s);
1149  if (!acc || xaccAccountGetType(acc) != ACCT_TYPE_TRADING)
1150  {
1151  imbal = gnc_numeric_add(imbal, xaccSplitGetValue(s),
1153  }
1154  else
1155  {
1156  imbal_trading = gnc_numeric_add(imbal_trading, xaccSplitGetValue(s),
1158  }
1159  }
1160  );
1161  }
1162  else
1163  imbal = xaccTransGetImbalanceValue(trans);
1164 
1165  if (! gnc_numeric_zero_p(imbal) || ! gnc_numeric_zero_p(imbal_trading))
1166  return FALSE;
1167 
1168  if (!xaccTransUseTradingAccounts (trans))
1169  return TRUE;
1170 
1171  imbal_list = xaccTransGetImbalance(trans);
1172  result = imbal_list == NULL;
1173  gnc_monetary_list_free(imbal_list);
1174  return result;
1175 }
gboolean xaccTransUseTradingAccounts(const Transaction *trans)
Determine whether this transaction should use commodity trading accounts.
Definition: Transaction.c:1023
GNCAccountType xaccAccountGetType(const Account *acc)
Returns the account&#39;s account type.
Definition: Account.cpp:3162
STRUCTS.
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:1044
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:74
Account * xaccSplitGetAccount(const Split *split)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: gmock-Split.cpp:45
MonetaryList * xaccTransGetImbalance(const Transaction *trans)
The xaccTransGetImbalance method returns a list giving the value of the transaction in each currency ...
Definition: Transaction.c:1060
#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 121 of file gmock-Transaction.cpp.

122 {
123  g_return_val_if_fail(GNC_IS_MOCK_TRANSACTION(trans), FALSE);
124  return ((MockTransaction*)trans)->isOpen();
125 }

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

2536 {
2537  GDate *threshold_date;
2538  GDate trans_date;
2539  const QofBook *book = xaccTransGetBook (trans);
2540  gboolean result;
2541  g_assert(trans);
2542 
2543  if (!qof_book_uses_autoreadonly(book))
2544  {
2545  return FALSE;
2546  }
2547 
2548  if (xaccTransIsSXTemplate (trans))
2549  return FALSE;
2550 
2551  threshold_date = qof_book_get_autoreadonly_gdate(book);
2552  g_assert(threshold_date); // ok because we checked uses_autoreadonly before
2553  trans_date = xaccTransGetDatePostedGDate(trans);
2554 
2555 // g_warning("there is auto-read-only with days=%d, trans_date_day=%d, threshold_date_day=%d",
2556 // qof_book_get_num_days_autofreeze(book),
2557 // g_date_get_day(&trans_date),
2558 // g_date_get_day(threshold_date));
2559 
2560  if (g_date_compare(&trans_date, threshold_date) < 0)
2561  {
2562  //g_warning("we are auto-read-only");
2563  result = TRUE;
2564  }
2565  else
2566  {
2567  result = FALSE;
2568  }
2569  g_date_free(threshold_date);
2570  return result;
2571 }
GDate * qof_book_get_autoreadonly_gdate(const QofBook *book)
Returns the GDate that is the threshold for auto-read-only.
Definition: qofbook.cpp:1113
#define xaccTransGetBook(X)
Definition: Transaction.h:773
gboolean qof_book_uses_autoreadonly(const QofBook *book)
Returns TRUE if the auto-read-only feature should be used, otherwise FALSE.
Definition: qofbook.cpp:1087
GDate xaccTransGetDatePostedGDate(const Transaction *trans)
Retrieve the posted date of the transaction.
Definition: Transaction.c:2414

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

1033 {
1034  QofCollection *col;
1035  if (!guid || !book) return NULL;
1036  col = qof_book_get_collection (book, GNC_ID_TRANS);
1037  return (Transaction *) qof_collection_lookup_entity (col, guid);
1038 }
QofInstance * qof_collection_lookup_entity(const QofCollection *col, const GncGUID *guid)
Find the entity going only from its guid.
Definition: qofid.cpp:214
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 1883 of file Transaction.c.

1884 {
1885  return xaccTransOrder_num_action (ta, NULL, tb, NULL);
1886 }
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:1889

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

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

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

2449 {
2450  return trans ? trans->date_entered : 0;
2451 }

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

2409 {
2410  return trans ? trans->date_posted : 0;
2411 }

◆ xaccTransReverse()

Transaction* xaccTransReverse ( Transaction *  transaction)

xaccTransReverse creates a Transaction that reverses the given tranaction 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 2792 of file Transaction.c.

2793 {
2794  Transaction *trans;
2795  GValue v = G_VALUE_INIT;
2796  g_return_val_if_fail(orig, NULL);
2797 
2798  trans = xaccTransClone(orig);
2799  xaccTransBeginEdit(trans);
2800 
2801  /* Reverse the values on each split. Clear per-split info. */
2802  FOR_EACH_SPLIT(trans,
2803  {
2807  });
2808 
2809  /* Now update the original with a pointer to the new one */
2810  g_value_init (&v, GNC_TYPE_GUID);
2811  g_value_set_boxed (&v, xaccTransGetGUID(trans));
2812  qof_instance_set_kvp (QOF_INSTANCE (orig), &v, 1, TRANS_REVERSED_BY);
2813 
2814  /* Make sure the reverse transaction is not read-only */
2815  xaccTransClearReadOnly(trans);
2816 
2817  qof_instance_set_dirty(QOF_INSTANCE(trans));
2818  xaccTransCommitEdit(trans);
2819  return trans;
2820 }
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:81
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:67
Transaction * xaccTransClone(const Transaction *from)
The xaccTransClone() method will create a complete copy of an existing transaction.
Definition: Transaction.c:676
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1643
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1444
#define xaccTransGetGUID(X)
Definition: Transaction.h:775
gnc_numeric xaccSplitGetValue(const Split *split)
Returns the value of this split in the transaction&#39;s commodity.
Definition: gmock-Split.cpp:74
#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:60

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

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

2893 {
2894  SplitList *node;
2895 
2896  ENTER("(trans=%p)", trans);
2897  /* Lock down posted date, its to be synced to the posted date
2898  * for the source of the cap gains. */
2899  xaccTransScrubGainsDate(trans);
2900 
2901  /* Fix up the split amount */
2902 restart:
2903  for (node = trans->splits; node; node = node->next)
2904  {
2905  Split *s = node->data;
2906 
2907  if (!xaccTransStillHasSplit(trans, s)) continue;
2908 
2909  xaccSplitDetermineGainStatus(s);
2910  if (s->gains & GAINS_STATUS_ADIRTY)
2911  {
2912  gboolean altered = FALSE;
2913  s->gains &= ~GAINS_STATUS_ADIRTY;
2914  if (s->lot)
2915  altered = xaccScrubLot(s->lot);
2916  else
2917  altered = xaccSplitAssign(s);
2918  if (altered) goto restart;
2919  }
2920  }
2921 
2922  /* Fix up gains split value */
2923  FOR_EACH_SPLIT(trans,
2924  if ((s->gains & GAINS_STATUS_VDIRTY) ||
2925  (s->gains_split &&
2926  (s->gains_split->gains & GAINS_STATUS_VDIRTY)))
2927  xaccSplitComputeCapGains(s, gain_acc);
2928  );
2929 
2930  LEAVE("(trans=%p)", trans);
2931 }
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:270
GList SplitList
GList of Split.
Definition: gnc-engine.h:207
gboolean xaccSplitAssign(Split *split)
The`xaccSplitAssign() routine will take the indicated split and, if it doesn&#39;t already belong to a lo...
Definition: cap-gains.c:428
#define LEAVE(format, args...)
Print a function exit debugging message.
Definition: qoflog.h:280
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 1415 of file Transaction.c.

1416 {
1417  gnc_commodity *old_curr = trans->common_currency;
1418  if (!trans || !curr || trans->common_currency == curr) return;
1419  xaccTransBeginEdit(trans);
1420 
1421  trans->common_currency = curr;
1422  if (old_curr != NULL && trans->splits != NULL)
1423  {
1424  gnc_numeric rate = find_new_rate(trans, curr);
1425  if (!gnc_numeric_zero_p (rate))
1426  {
1427  FOR_EACH_SPLIT(trans, split_set_new_value(s, curr, old_curr, rate));
1428  }
1429  else
1430  {
1431  FOR_EACH_SPLIT(trans, xaccSplitSetValue(s, xaccSplitGetValue(s)));
1432  }
1433  }
1434 
1435  qof_instance_set_dirty(QOF_INSTANCE(trans));
1436  mark_trans(trans); /* Dirty balance of every account in trans */
1437  xaccTransCommitEdit(trans);
1438 }
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:81
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:1643
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1444
gnc_numeric xaccSplitGetValue(const Split *split)
Returns the value of this split in the transaction&#39;s commodity.
Definition: gmock-Split.cpp:74

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

2038 {
2039  GDate *date;
2040  if (!trans) return;
2041  date = g_date_new_dmy(day, mon, year);
2042  if (!g_date_valid(date))
2043  {
2044  PWARN("Attempted to set invalid date %d-%d-%d; set today's date instead.",
2045  year, mon, day);
2046  g_free(date);
2047  date = gnc_g_date_new_today();
2048  }
2049  xaccTransSetDatePostedGDate(trans, *date);
2050  g_free(date);
2051 }
void xaccTransSetDatePostedGDate(Transaction *trans, GDate date)
This method modifies posted date of the transaction, specified by a GDate.
Definition: Transaction.c:1993
#define PWARN(format, args...)
Log a warning.
Definition: qoflog.h:252
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 2011 of file Transaction.c.

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

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

1994 {
1995  GValue v = G_VALUE_INIT;
1996  if (!trans) return;
1997 
1998  /* We additionally save this date into a kvp frame to ensure in
1999  * the future a date which was set as *date* (without time) can
2000  * clearly be distinguished from the time64. */
2001  g_value_init (&v, G_TYPE_DATE);
2002  g_value_set_boxed (&v, &date);
2003  qof_instance_set_kvp (QOF_INSTANCE(trans), &v, 1, TRANS_DATE_POSTED);
2004  /* mark dirty and commit handled by SetDateInternal */
2005  xaccTransSetDateInternal(trans, &trans->date_posted,
2006  gdate_to_time64(date));
2007  set_gains_date_dirty (trans);
2008 }
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 1977 of file Transaction.c.

1978 {
1979  if (!trans) return;
1980  xaccTransSetDateInternal(trans, &trans->date_posted, secs);
1981  set_gains_date_dirty(trans);
1982 }

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

73 {
74  g_return_if_fail(GNC_IS_MOCK_TRANSACTION(trans));
75  ((MockTransaction*)trans)->setDatePostedSecsNormalized(time);
76 }

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

101 {
102  g_return_if_fail(GNC_IS_MOCK_TRANSACTION(trans));
103  ((MockTransaction*)trans)->setDescription(notes);
104 }

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

2097 {
2098  if (trans && reason)
2099  {
2100  GValue v = G_VALUE_INIT;
2101  g_value_init (&v, G_TYPE_STRING);
2102  g_value_set_string (&v, reason);
2103  xaccTransBeginEdit(trans);
2104  qof_instance_set_kvp (QOF_INSTANCE (trans), &v, 1, TRANS_READ_ONLY_REASON);
2105  qof_instance_set_dirty(QOF_INSTANCE(trans));
2106  xaccTransCommitEdit(trans);
2107 
2108  g_free (trans->readonly_reason);
2109  trans->readonly_reason = g_strdup (reason);
2110  trans->reason_cache_valid = TRUE;
2111  }
2112 }
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:1643
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1444

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

2068 {
2069  char s[2] = {type, '\0'};
2070  GValue v = G_VALUE_INIT;
2071  g_return_if_fail(trans);
2072  g_value_init (&v, G_TYPE_STRING);
2073  g_value_set_string (&v, s);
2074  xaccTransBeginEdit(trans);
2075  qof_instance_set_kvp (QOF_INSTANCE (trans), &v, 1, TRANS_TXN_TYPE_KVP);
2076  qof_instance_set_dirty(QOF_INSTANCE(trans));
2077  xaccTransCommitEdit(trans);
2078 }
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:1643
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1444

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

2766 {
2767  GValue v = G_VALUE_INIT;
2768  const char *s = NULL;
2769  g_return_if_fail(trans);
2770 
2771  qof_instance_get_kvp (QOF_INSTANCE (trans), &v, 1, void_reason_str);
2772  if (G_VALUE_HOLDS_STRING (&v))
2773  s = g_value_get_string (&v);
2774  if (s == NULL) return; /* Transaction isn't voided. Bail. */
2775  xaccTransBeginEdit(trans);
2776 
2777  qof_instance_get_kvp (QOF_INSTANCE (trans), &v, 1, void_former_notes_str);
2778  if (G_VALUE_HOLDS_STRING (&v))
2779  qof_instance_set_kvp (QOF_INSTANCE (trans), &v, 1, trans_notes_str);
2780  qof_instance_set_kvp (QOF_INSTANCE (trans), NULL, 1, void_former_notes_str);
2781  qof_instance_set_kvp (QOF_INSTANCE (trans), NULL, 1, void_reason_str);
2782  qof_instance_set_kvp (QOF_INSTANCE (trans), NULL, 1, void_time_str);
2783 
2784  FOR_EACH_SPLIT(trans, xaccSplitUnvoid(s));
2785 
2786  /* Dirtying taken care of by ClearReadOnly */
2787  xaccTransClearReadOnly(trans);
2788  xaccTransCommitEdit(trans);
2789 }
void qof_instance_set_kvp(QofInstance *, GValue const *value, unsigned count,...)
Sets a KVP slot to a value from a GValue.
void qof_instance_get_kvp(QofInstance *, GValue *value, unsigned count,...)
Retrieves the contents of a KVP slot into a provided GValue.
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1643
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1444

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

2686 {
2687  GValue v = G_VALUE_INIT;
2688  char iso8601_str[ISO_DATELENGTH + 1] = "";
2689 
2690  g_return_if_fail(trans && reason);
2691 
2692  /* Prevent voiding transactions that are already marked
2693  * read only, for example generated by the business features.
2694  */
2695  if (xaccTransGetReadOnly (trans))
2696  {
2697  PWARN ("Refusing to void a read-only transaction!");
2698  return;
2699  }
2700  xaccTransBeginEdit(trans);
2701  qof_instance_get_kvp (QOF_INSTANCE (trans), &v, 1, trans_notes_str);
2702  if (G_VALUE_HOLDS_STRING (&v))
2703  qof_instance_set_kvp (QOF_INSTANCE (trans), &v, 1, void_former_notes_str);
2704  else
2705  g_value_init (&v, G_TYPE_STRING);
2706 
2707  g_value_set_string (&v, _("Voided transaction"));
2708  qof_instance_set_kvp (QOF_INSTANCE (trans), &v, 1, trans_notes_str);
2709  g_value_set_string (&v, reason);
2710  qof_instance_set_kvp (QOF_INSTANCE (trans), &v, 1, void_reason_str);
2711 
2712  gnc_time64_to_iso8601_buff (gnc_time(NULL), iso8601_str);
2713  g_value_set_string (&v, iso8601_str);
2714  qof_instance_set_kvp (QOF_INSTANCE (trans), &v, 1, void_time_str);
2715 
2716  FOR_EACH_SPLIT(trans, xaccSplitVoid(s));
2717 
2718  /* Dirtying taken care of by SetReadOnly */
2719  xaccTransSetReadOnly(trans, _("Transaction Voided"));
2720  xaccTransCommitEdit(trans);
2721 }
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:2487
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:252
void xaccTransSetReadOnly(Transaction *trans, const char *reason)
Set the transaction to be ReadOnly by setting a non-NULL value as "reason".
Definition: Transaction.c:2096
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1643
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1444
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