GnuCash  2.7.0
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...
 
void xaccSplitSetDateReconciledTS (Split *split, Timespec *ts)
 Set the date on which this split was reconciled by specifying the time as Timespec. More...
 
void xaccSplitGetDateReconciledTS (const Split *split, Timespec *ts)
 Get the date on which this split was reconciled by having it written into the Timespec that 'ts' is pointing to. More...
 
Timespec xaccSplitRetDateReconciledTS (const Split *split)
 Returns the date (as Timespec) on which this split was reconciled. 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 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 xaccTransSetAssociation (Transaction *trans, const char *assoc)
 Sets the transaction Association.
 
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 * xaccTransGetAssociation (const Transaction *trans)
 Gets the transaction association.
 
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)
 The xaccTransGetSplit() method returns a pointer to each of the splits in this transaction. 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...
 
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)
 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 (const 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 xaccTransSetDatePostedTS (Transaction *trans, const Timespec *ts)
 The xaccTransSetDatePostedTS() method does the same thing as xaccTransSetDatePostedSecs(), but takes a struct timespec64. More...
 
void xaccTransSetDateEnteredSecs (Transaction *trans, time64 time)
 Modify the date of when the transaction was entered. More...
 
void xaccTransSetDateEnteredTS (Transaction *trans, const Timespec *ts)
 Modify the date of when the transaction was entered. More...
 
void xaccTransSetDateDueTS (Transaction *trans, const Timespec *ts)
 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...
 
void xaccTransGetDatePostedTS (const Transaction *trans, Timespec *ts)
 Retrieve the posted date of the transaction. More...
 
Timespec xaccTransRetDatePostedTS (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...
 
void xaccTransGetDateEnteredTS (const Transaction *trans, Timespec *ts)
 Retrieve the date of when the transaction was entered. More...
 
Timespec xaccTransRetDateEnteredTS (const Transaction *trans)
 Retrieve the date of when the transaction was entered. More...
 
Timespec xaccTransRetDateDueTS (const Transaction *trans)
 Dates and txn-type for A/R and A/P "invoice" postings.
 
void xaccTransGetDateDueTS (const Transaction *trans, Timespec *ts)
 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...
 
Timespec 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_ASSOCIATION   "assoc"
 
#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 549 of file Split.h.

◆ xaccSplitReturnGUID

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

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

◆ xaccTransGetBook

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

Definition at line 768 of file Transaction.h.

◆ xaccTransGetGUID

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

Definition at line 770 of file Transaction.h.

◆ xaccTransReturnGUID

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

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

2601 {
2602  guint count = 0;
2603  xaccAccountTreeForEachTransaction(gnc_book_get_root_account(book),
2604  counter_thunk, (void*)&count);
2605  return count;
2606 }
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 546 of file Split.c.

547 {
548  Split *split;
549  g_return_val_if_fail (book, NULL);
550 
551  split = g_object_new (GNC_TYPE_SPLIT, NULL);
552  xaccInitSplit (split, book);
553 
554  return split;
555 }

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

517 {
518  Transaction *trans;
519 
520  g_return_val_if_fail (book, NULL);
521 
522  trans = g_object_new(GNC_TYPE_TRANSACTION, NULL);
523  xaccInitTransaction (trans, book);
524  qof_event_gen (&trans->inst, QOF_EVENT_CREATE, NULL);
525 
526  return trans;
527 }
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 2018 of file Split.c.

2020 {
2021  const GncGUID* guid;
2022 
2023  g_return_if_fail (split != NULL);
2024  g_return_if_fail (other_split != NULL);
2025 
2026  guid = qof_instance_get_guid (QOF_INSTANCE (other_split));
2027  xaccTransBeginEdit (split->parent);
2028  qof_instance_kvp_add_guid (QOF_INSTANCE (split), "lot-split",
2029  timespec_now(), "peer_guid", guid_copy(guid));
2030  mark_split (split);
2031  qof_instance_set_dirty (QOF_INSTANCE (split));
2032  xaccTransCommitEdit (split->parent);
2033 }
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...
Definition: Transaction.c:1641
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1442
Timespec timespec_now()
Returns the current clock time as a Timespec, taken from time(2).
Definition: gnc-date.cpp:1312
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 1658 of file Split.c.

1659 {
1660  Account *aa, *ab;
1661  if (!sa && !sb) return 0;
1662  if (!sa) return -1;
1663  if (!sb) return 1;
1664 
1665  aa = sa->acc;
1666  ab = sb->acc;
1667 
1668  return g_strcmp0(xaccAccountGetCode(aa), xaccAccountGetCode(ab));
1669 }
const char * xaccAccountGetCode(const Account *acc)
Get the account's accounting code.
Definition: Account.c:3086
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 1637 of file Split.c.

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

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

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

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

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

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

651 {
652  if (!from_split || !to_split) return;
653  xaccTransBeginEdit (to_split->parent);
654 
655  xaccSplitSetMemo(to_split, xaccSplitGetMemo(from_split));
656  xaccSplitSetAction(to_split, xaccSplitGetAction(from_split));
657  xaccSplitSetAmount(to_split, xaccSplitGetAmount(from_split));
658  xaccSplitSetValue(to_split, xaccSplitGetValue(from_split));
659  /* Setting the account is okay here because, even though the from
660  split might not really belong to the account it claims to,
661  setting the account won't cause any event involving from. */
662  xaccSplitSetAccount(to_split, xaccSplitGetAccount(from_split));
663  /* N.B. Don't set parent. */
664 
665  qof_instance_set_dirty(QOF_INSTANCE(to_split));
666  xaccTransCommitEdit(to_split->parent);
667 }
void xaccSplitSetValue(Split *s, gnc_numeric amt)
The xaccSplitSetValue() method sets the value of this split in the transaction's commodity.
Definition: Split.c:1258
void xaccSplitSetAction(Split *split, const char *actn)
The Action is an arbitrary user-assigned string.
Definition: Split.c:1732
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:1222
void xaccSplitSetMemo(Split *split, const char *memo)
The memo is an arbitrary string associated with a split.
Definition: Split.c:1713
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1641
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1442
gnc_numeric xaccSplitGetValue(const Split *split)
Returns the value of this split in the transaction's commodity.
Definition: Split.c:1932
Account * xaccSplitGetAccount(const Split *s)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: Split.c:929
const char * xaccSplitGetMemo(const Split *split)
Returns the memo string.
Definition: Split.c:1907
const char * xaccSplitGetAction(const Split *split)
Returns the action string.
Definition: Split.c:1913
gnc_numeric xaccSplitGetAmount(const Split *split)
Returns the amount of the split in the account's commodity.
Definition: Split.c:1926

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

1457 {
1458  Account *acc;
1459  Transaction *trans;
1460  GncEventData ed;
1461 
1462  if (!split) return TRUE;
1463 
1464  acc = split->acc;
1465  trans = split->parent;
1466  if (acc && !qof_instance_get_destroying(acc)
1467  && xaccTransGetReadOnly(trans))
1468  return FALSE;
1469 
1470  xaccTransBeginEdit(trans);
1471  ed.node = split;
1472  ed.idx = xaccTransGetSplitIndex(trans, split);
1473  qof_instance_set_dirty(QOF_INSTANCE(split));
1474  qof_instance_set_destroying(split, TRUE);
1475  qof_event_gen(&trans->inst, GNC_EVENT_ITEM_REMOVED, &ed);
1476  xaccTransCommitEdit(trans);
1477 
1478  return TRUE;
1479 }
STRUCTS.
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...
Definition: Transaction.c:1641
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1442
const char * xaccTransGetReadOnly(const Transaction *trans)
Returns a non-NULL value if this Transaction was marked as read-only with some specific "reason" text...
Definition: Transaction.c:2422
int xaccTransGetSplitIndex(const Transaction *trans, const Split *split)
Inverse of xaccTransGetSplit()
Definition: Transaction.c:2229
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 776 of file Split.c.

780 {
781  gboolean same_book;
782 
783  if (!sa && !sb) return TRUE; /* Arguable. FALSE is better, methinks */
784 
785  if (!sa || !sb)
786  {
787  PINFO ("one is NULL");
788  return FALSE;
789  }
790 
791  if (sa == sb) return TRUE;
792 
793  same_book = qof_instance_get_book(QOF_INSTANCE(sa)) == qof_instance_get_book(QOF_INSTANCE(sb));
794 
795  if (check_guids)
796  {
797  if (qof_instance_guid_compare(sa, sb) != 0)
798  {
799  PINFO ("GUIDs differ");
800  return FALSE;
801  }
802  }
803 
804  /* If the same book, since these strings are cached we can just use pointer equality */
805  if ((same_book && sa->memo != sb->memo) || (!same_book && g_strcmp0(sa->memo, sb->memo) != 0))
806  {
807  PINFO ("memos differ: (%p)%s vs (%p)%s",
808  sa->memo, sa->memo, sb->memo, sb->memo);
809  return FALSE;
810  }
811 
812  if ((same_book && sa->action != sb->action) || (!same_book && g_strcmp0(sa->action, sb->action) != 0))
813  {
814  PINFO ("actions differ: %s vs %s", sa->action, sb->action);
815  return FALSE;
816  }
817 
818  if (qof_instance_compare_kvp (QOF_INSTANCE (sa), QOF_INSTANCE (sb)) != 0)
819  {
820  char *frame_a;
821  char *frame_b;
822 
823  frame_a = qof_instance_kvp_as_string (QOF_INSTANCE (sa));
824  frame_b = qof_instance_kvp_as_string (QOF_INSTANCE (sb));
825 
826  PINFO ("kvp frames differ:\n%s\n\nvs\n\n%s", frame_a, frame_b);
827 
828  g_free (frame_a);
829  g_free (frame_b);
830 
831  return FALSE;
832  }
833 
834  if (sa->reconciled != sb->reconciled)
835  {
836  PINFO ("reconcile flags differ: %c vs %c", sa->reconciled, sb->reconciled);
837  return FALSE;
838  }
839 
840  if (timespec_cmp(&(sa->date_reconciled), &(sb->date_reconciled)))
841  {
842  PINFO ("reconciled date differs");
843  return FALSE;
844  }
845 
847  {
848  char *str_a;
849  char *str_b;
850 
853 
854  PINFO ("amounts differ: %s vs %s", str_a, str_b);
855 
856  g_free (str_a);
857  g_free (str_b);
858 
859  return FALSE;
860  }
861 
863  {
864  char *str_a;
865  char *str_b;
866 
869 
870  PINFO ("values differ: %s vs %s", str_a, str_b);
871 
872  g_free (str_a);
873  g_free (str_b);
874 
875  return FALSE;
876  }
877 
878  if (check_balances)
879  {
880  if (!xaccSplitEqualCheckBal ("", sa->balance, sb->balance))
881  return FALSE;
882  if (!xaccSplitEqualCheckBal ("cleared ", sa->cleared_balance,
883  sb->cleared_balance))
884  return FALSE;
885  if (!xaccSplitEqualCheckBal ("reconciled ", sa->reconciled_balance,
886  sb->reconciled_balance))
887  return FALSE;
888  }
889 
890  if (!xaccTransEqual(sa->parent, sb->parent, check_guids, check_txn_splits,
891  check_balances, FALSE))
892  {
893  PINFO ("transactions differ");
894  return FALSE;
895  }
896 
897  return TRUE;
898 }
QofBook * qof_instance_get_book(gconstpointer inst)
Return the book pointer.
#define PINFO(format, args...)
Print an informational note.
Definition: qoflog.h:249
gchar * gnc_numeric_to_string(gnc_numeric n)
Convert to string.
gint timespec_cmp(const Timespec *ta, const Timespec *tb)
comparison: if (ta < tb) -1; else if (ta > tb) 1; else 0;
Definition: gnc-date.cpp:431
gboolean xaccTransEqual(const Transaction *ta, const Transaction *tb, gboolean check_guids, gboolean check_splits, gboolean check_balances, gboolean assume_ordered)
Equality.
Definition: Transaction.c:862
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&#39;s commodity.
Definition: Split.c:1932
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&#39;s commodity.
Definition: Split.c:1926

◆ xaccSplitGetAccount()

Account* xaccSplitGetAccount ( const Split *  split)

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

Definition at line 929 of file Split.c.

930 {
931  return s ? s->acc : NULL;
932 }

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

1914 {
1915  return split ? split->action : NULL;
1916 }

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

1927 {
1928  return split ? split->amount : gnc_numeric_zero();
1929 }

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

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

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

1361 {
1362  if (!s || !s->acc || !s->parent) return gnc_numeric_zero();
1363 
1364  /* be more precise -- the value depends on the currency we want it
1365  * expressed in. */
1366  if (gnc_commodity_equiv(xaccTransGetCurrency(s->parent), base_currency))
1367  return xaccSplitGetValue(s);
1368  if (gnc_commodity_equiv(xaccAccountGetCommodity(s->acc), base_currency))
1369  return xaccSplitGetAmount(s);
1370 
1371  PERR ("inappropriate base currency %s "
1372  "given split currency=%s and commodity=%s\n",
1373  gnc_commodity_get_printname(base_currency),
1376  return gnc_numeric_zero();
1377 }
#define PERR(format, args...)
Log a serious error.
Definition: qoflog.h:237
const char * gnc_commodity_get_printname(const gnc_commodity *cm)
Retrieve the &#39;print&#39; name for the specified commodity.
gnc_numeric xaccSplitGetValue(const Split *split)
Returns the value of this split in the transaction&#39;s commodity.
Definition: Split.c:1932
gnc_commodity * xaccAccountGetCommodity(const Account *acc)
Get the account&#39;s commodity.
Definition: Account.c:3154
gnc_commodity * xaccTransGetCurrency(const Transaction *trans)
Returns the valuation commodity of this transaction.
Definition: Transaction.c:1354
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: Split.c:1926

◆ xaccSplitGetBook()

QofBook* xaccSplitGetBook ( const Split *  split)

Returns the book of this split, i.e.

the entity where this split is stored.

Definition at line 1981 of file Split.c.

1982 {
1983  return qof_instance_get_book(QOF_INSTANCE(split));
1984 }
QofBook * qof_instance_get_book(gconstpointer inst)
Return the book pointer.

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

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

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

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

◆ xaccSplitGetDateReconciled()

time64 xaccSplitGetDateReconciled ( const Split *  split)

Retrieve the date when the Split was reconciled.

Definition at line 1831 of file Split.c.

1832 {
1833  return split ? split->date_reconciled.tv_sec : 0;
1834 }

◆ xaccSplitGetDateReconciledTS()

void xaccSplitGetDateReconciledTS ( const Split *  split,
Timespec *  ts 
)

Get the date on which this split was reconciled by having it written into the Timespec that 'ts' is pointing to.

Definition at line 1816 of file Split.c.

1817 {
1818  if (!split || !ts) return;
1819  *ts = (split->date_reconciled);
1820 }

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

1893 {
1894  return split ? split->lot : NULL;
1895 }

◆ xaccSplitGetMemo()

const char* xaccSplitGetMemo ( const Split *  split)

Returns the memo string.

Definition at line 1907 of file Split.c.

1908 {
1909  return split ? split->memo : NULL;
1910 }

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

2096 {
2097  int i;
2098  Transaction *trans;
2099  int count, num_splits;
2100  Split *other = NULL;
2101  gboolean lot_split;
2102  gboolean trading_accts;
2103 
2104  if (!split) return NULL;
2105  trans = split->parent;
2106  if (!trans) return NULL;
2107 
2108  trading_accts = xaccTransUseTradingAccounts (trans);
2109  num_splits = xaccTransCountSplits(trans);
2110  count = num_splits;
2111  lot_split = qof_instance_has_slot(QOF_INSTANCE (split), "lot-split");
2112  if (!lot_split && !trading_accts && (2 != count)) return NULL;
2113 
2114  for (i = 0; i < num_splits; i++)
2115  {
2116  Split *s = xaccTransGetSplit(trans, i);
2117  if (s == split)
2118  {
2119  --count;
2120  continue;
2121  }
2122  if (qof_instance_has_slot (QOF_INSTANCE (s), "lot-split"))
2123  {
2124  --count;
2125  continue;
2126  }
2127  if (trading_accts &&
2129  {
2130  --count;
2131  continue;
2132  }
2133  other = s;
2134  }
2135  return (1 == count) ? other : NULL;
2136 }
Split * xaccTransGetSplit(const Transaction *trans, int i)
The xaccTransGetSplit() method returns a pointer to each of the splits in this transaction.
Definition: Transaction.c:2219
gboolean xaccTransUseTradingAccounts(const Transaction *trans)
Determine whether this transaction should use commodity trading accounts.
Definition: Transaction.c:1021
GNCAccountType xaccAccountGetType(const Account *acc)
Returns the account&#39;s account type.
Definition: Account.c:3009
Account used to record multiple commodity transactions.
Definition: Account.h:155
int xaccTransCountSplits(const Transaction *trans)
Returns the number of splits in this transaction.
Definition: Transaction.c:2267
Account * xaccSplitGetAccount(const Split *s)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: Split.c:929

◆ xaccSplitGetParent()

Transaction* xaccSplitGetParent ( const Split *  split)

Returns the parent transaction of the split.

Definition at line 1842 of file Split.c.

1843 {
1844  return split ? split->parent : NULL;
1845 }

◆ xaccSplitGetReconcile()

char xaccSplitGetReconcile ( const Split *  split)

Returns the value of the reconcile flag.

Definition at line 1919 of file Split.c.

1920 {
1921  return split ? split->reconciled : ' ';
1922 }

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

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

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

1939 {
1940  gnc_numeric amt, val, price;
1941  if (!split) return gnc_numeric_create(1, 1);
1942 
1943 
1944  /* if amount == 0 and value == 0, then return 1.
1945  * if amount == 0 and value != 0 then return 0.
1946  * otherwise return value/amount
1947  */
1948 
1949  amt = xaccSplitGetAmount(split);
1950  val = xaccSplitGetValue(split);
1951  if (gnc_numeric_zero_p(amt))
1952  {
1953  if (gnc_numeric_zero_p(val))
1954  return gnc_numeric_create(1, 1);
1955  return gnc_numeric_create(0, 1);
1956  }
1957  price = gnc_numeric_div(val, amt,
1959  GNC_HOW_DENOM_SIGFIGS(PRICE_SIGFIGS) |
1961 
1962  /* During random checks we can get some very weird prices. Let's
1963  * handle some overflow and other error conditions by returning
1964  * zero. But still print an error to let us know it happened.
1965  */
1966  if (gnc_numeric_check(price))
1967  {
1968  PERR("Computing share price failed (%d): [ %" G_GINT64_FORMAT " / %"
1969  G_GINT64_FORMAT " ] / [ %" G_GINT64_FORMAT " / %" G_GINT64_FORMAT " ]",
1970  gnc_numeric_check(price), val.num, val.denom, amt.num, amt.denom);
1971  return gnc_numeric_create(0, 1);
1972  }
1973 
1974  return price;
1975 }
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:237
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&#39;s commodity.
Definition: Split.c:1932
GNCNumericErrorCode gnc_numeric_check(gnc_numeric in)
Check for error signal in value.
#define GNC_DENOM_AUTO
Values that can be passed as the &#39;denom&#39; argument.
Definition: gnc-numeric.h:246
#define GNC_HOW_DENOM_SIGFIGS(n)
Build a &#39;how&#39; value that will generate a denominator that will keep at least n significant figures in...
Definition: gnc-numeric.h:218
gnc_numeric xaccSplitGetAmount(const Split *split)
Returns the amount of the split in the account&#39;s commodity.
Definition: Split.c:1926

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

1988 {
1989  GValue v = G_VALUE_INIT;
1990  const char *split_type = NULL;
1991 
1992  if (!s) return NULL;
1993  qof_instance_get_kvp (QOF_INSTANCE (s), "split-type", &v);
1994  if (G_VALUE_HOLDS_STRING (&v))
1995  split_type = g_value_get_string (&v);
1996  return split_type ? split_type : "normal";
1997 }
void qof_instance_get_kvp(const QofInstance *inst, const gchar *key, GValue *value)
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 1932 of file Split.c.

1933 {
1934  return split ? split->value : gnc_numeric_zero();
1935 }

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

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

1066 {
1067  QofCollection *col;
1068  if (!guid || !book) return NULL;
1069  col = qof_book_get_collection (book, GNC_ID_SPLIT);
1070  return (Split *) qof_collection_lookup_entity (col, guid);
1071 }
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:599

◆ xaccSplitMakeStockSplit()

void xaccSplitMakeStockSplit ( Split *  s)

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

Definition at line 2002 of file Split.c.

2003 {
2004  GValue v = G_VALUE_INIT;
2005  xaccTransBeginEdit (s->parent);
2006 
2007  s->value = gnc_numeric_zero();
2008  g_value_init (&v, G_TYPE_STRING);
2009  g_value_set_string (&v, "stock-split");
2010  qof_instance_set_kvp (QOF_INSTANCE (s), "split-type", &v);
2011  SET_GAINS_VDIRTY(s);
2012  mark_split(s);
2013  qof_instance_set_dirty(QOF_INSTANCE(s));
2014  xaccTransCommitEdit(s->parent);
2015 }
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1641
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1442
void qof_instance_set_kvp(QofInstance *inst, const gchar *key, const GValue *value)
Sets a KVP slot to a value from a GValue.

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

2073 {
2074  xaccTransBeginEdit (split->parent);
2075  qof_instance_kvp_merge_guids (QOF_INSTANCE (split),
2076  QOF_INSTANCE (other_split), "lot-split");
2077  mark_split (split);
2078  qof_instance_set_dirty (QOF_INSTANCE (split));
2079  xaccTransCommitEdit (split->parent);
2080 }
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1641
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1442

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

1486 {
1487  int retval;
1488  int comp;
1489  char *da, *db;
1490  gboolean action_for_num;
1491 
1492  if (sa == sb) return 0;
1493  /* nothing is always less than something */
1494  if (!sa) return -1;
1495  if (!sb) return +1;
1496 
1497  /* sort in transaction order, but use split action rather than trans num
1498  * according to book option */
1500  (xaccSplitGetBook (sa));
1501  if (action_for_num)
1502  retval = xaccTransOrder_num_action (sa->parent, sa->action,
1503  sb->parent, sb->action);
1504  else
1505  retval = xaccTransOrder (sa->parent, sb->parent);
1506  if (retval) return retval;
1507 
1508  /* otherwise, sort on memo strings */
1509  da = sa->memo ? sa->memo : "";
1510  db = sb->memo ? sb->memo : "";
1511  retval = g_utf8_collate (da, db);
1512  if (retval)
1513  return retval;
1514 
1515  /* otherwise, sort on action strings */
1516  da = sa->action ? sa->action : "";
1517  db = sb->action ? sb->action : "";
1518  retval = g_utf8_collate (da, db);
1519  if (retval != 0)
1520  return retval;
1521 
1522  /* the reconciled flag ... */
1523  if (sa->reconciled < sb->reconciled) return -1;
1524  if (sa->reconciled > sb->reconciled) return +1;
1525 
1526  /* compare amounts */
1528  if (comp < 0) return -1;
1529  if (comp > 0) return +1;
1530 
1532  if (comp < 0) return -1;
1533  if (comp > 0) return +1;
1534 
1535  /* if dates differ, return */
1536  DATE_CMP(sa, sb, date_reconciled);
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...
Definition: qofbook.cpp:1042
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:1981
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:1887
gnc_numeric xaccSplitGetValue(const Split *split)
Returns the value of this split in the transaction&#39;s commodity.
Definition: Split.c:1932
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:1881
gnc_numeric xaccSplitGetAmount(const Split *split)
Returns the amount of the split in the account&#39;s commodity.
Definition: Split.c:1926

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

2056 {
2057  const GncGUID* guid;
2058 
2059  g_return_if_fail (split != NULL);
2060  g_return_if_fail (other_split != NULL);
2061 
2062  guid = qof_instance_get_guid (QOF_INSTANCE (other_split));
2063  xaccTransBeginEdit (split->parent);
2064  qof_instance_kvp_remove_guid (QOF_INSTANCE (split), "lot-split",
2065  "peer_guid", guid);
2066  mark_split (split);
2067  qof_instance_set_dirty (QOF_INSTANCE (split));
2068  xaccTransCommitEdit (split->parent);
2069 }
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...
Definition: Transaction.c:1641
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1442
The type used to store guids in C.
Definition: guid.h:75

◆ xaccSplitRetDateReconciledTS()

Timespec xaccSplitRetDateReconciledTS ( const Split *  split)

Returns the date (as Timespec) on which this split was reconciled.

Definition at line 1823 of file Split.c.

1824 {
1825  Timespec ts = {0, 0};
1826  return split ? split->date_reconciled : ts;
1827 }

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

1733 {
1734  if (!split || !actn) return;
1735  xaccTransBeginEdit (split->parent);
1736 
1737  CACHE_REPLACE(split->action, actn);
1738  qof_instance_set_dirty(QOF_INSTANCE(split));
1739  xaccTransCommitEdit(split->parent);
1740 
1741 }
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1641
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1442

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

1223 {
1224  if (!s) return;
1225  g_return_if_fail(gnc_numeric_check(amt) == GNC_ERROR_OK);
1226  ENTER ("(split=%p) old amt=%" G_GINT64_FORMAT "/%" G_GINT64_FORMAT
1227  " new amt=%" G_GINT64_FORMAT "/%" G_GINT64_FORMAT, s,
1228  s->amount.num, s->amount.denom, amt.num, amt.denom);
1229 
1230  xaccTransBeginEdit (s->parent);
1231  if (s->acc)
1232  {
1233  s->amount = gnc_numeric_convert(amt, get_commodity_denom(s),
1235  g_assert (gnc_numeric_check (s->amount) == GNC_ERROR_OK);
1236  }
1237  else
1238  s->amount = amt;
1239 
1240  SET_GAINS_ADIRTY(s);
1241  mark_split (s);
1242  qof_instance_set_dirty(QOF_INSTANCE(s));
1243  xaccTransCommitEdit(s->parent);
1244  LEAVE("");
1245 }
#define ENTER(format, args...)
Print a function entry debugging message.
Definition: qoflog.h:261
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...
Definition: Transaction.c:1641
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1442
#define LEAVE(format, args...)
Print a function exit debugging message.
Definition: qoflog.h:271
GNCNumericErrorCode gnc_numeric_check(gnc_numeric in)
Check for error signal in value.
No error.
Definition: gnc-numeric.h:224

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

1307 {
1308  const gnc_commodity *currency;
1309  const gnc_commodity *commodity;
1310 
1311  if (!s) return;
1312  xaccTransBeginEdit (s->parent);
1313 
1314  if (!s->acc)
1315  {
1316  PERR ("split must have a parent account");
1317  return;
1318  }
1319 
1320  currency = xaccTransGetCurrency (s->parent);
1321  commodity = xaccAccountGetCommodity (s->acc);
1322 
1323  /* If the base_currency is the transaction's commodity ('currency'),
1324  * set the value. If it's the account commodity, set the
1325  * amount. If both, set both. */
1326  if (gnc_commodity_equiv(currency, base_currency))
1327  {
1328  if (gnc_commodity_equiv(commodity, base_currency))
1329  {
1330  s->amount = gnc_numeric_convert(value,
1331  get_commodity_denom(s),
1333  }
1334  s->value = gnc_numeric_convert(value,
1335  get_currency_denom(s),
1337  }
1338  else if (gnc_commodity_equiv(commodity, base_currency))
1339  {
1340  s->amount = gnc_numeric_convert(value, get_commodity_denom(s),
1342  }
1343  else
1344  {
1345  PERR ("inappropriate base currency %s "
1346  "given split currency=%s and commodity=%s\n",
1347  gnc_commodity_get_printname(base_currency),
1348  gnc_commodity_get_printname(currency),
1349  gnc_commodity_get_printname(commodity));
1350  return;
1351  }
1352 
1353  SET_GAINS_A_VDIRTY(s);
1354  mark_split (s);
1355  qof_instance_set_dirty(QOF_INSTANCE(s));
1356  xaccTransCommitEdit(s->parent);
1357 }
#define PERR(format, args...)
Log a serious error.
Definition: qoflog.h:237
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...
Definition: Transaction.c:1641
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1442
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.c:3154
gnc_commodity * xaccTransGetCurrency(const Transaction *trans)
Returns the valuation commodity of this transaction.
Definition: Transaction.c:1354
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 1791 of file Split.c.

1792 {
1793  if (!split) return;
1794  xaccTransBeginEdit (split->parent);
1795 
1796  split->date_reconciled.tv_sec = secs;
1797  split->date_reconciled.tv_nsec = 0;
1798  qof_instance_set_dirty(QOF_INSTANCE(split));
1799  xaccTransCommitEdit(split->parent);
1800 
1801 }
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1641
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1442

◆ xaccSplitSetDateReconciledTS()

void xaccSplitSetDateReconciledTS ( Split *  split,
Timespec *  ts 
)

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

Caller still owns *ts!

Definition at line 1804 of file Split.c.

1805 {
1806  if (!split || !ts) return;
1807  xaccTransBeginEdit (split->parent);
1808 
1809  split->date_reconciled = *ts;
1810  qof_instance_set_dirty(QOF_INSTANCE(split));
1811  xaccTransCommitEdit(split->parent);
1812 
1813 }
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1641
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1442

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

1714 {
1715  if (!split || !memo) return;
1716  xaccTransBeginEdit (split->parent);
1717 
1718  CACHE_REPLACE(split->memo, memo);
1719  qof_instance_set_dirty(QOF_INSTANCE(split));
1720  xaccTransCommitEdit(split->parent);
1721 
1722 }
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1641
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1442

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

1766 {
1767  if (!split || split->reconciled == recn) return;
1768  xaccTransBeginEdit (split->parent);
1769 
1770  switch (recn)
1771  {
1772  case NREC:
1773  case CREC:
1774  case YREC:
1775  case FREC:
1776  case VREC:
1777  split->reconciled = recn;
1778  mark_split (split);
1779  qof_instance_set_dirty(QOF_INSTANCE(split));
1780  xaccAccountRecomputeBalance (split->acc);
1781  break;
1782  default:
1783  PERR("Bad reconciled flag");
1784  break;
1785  }
1786  xaccTransCommitEdit(split->parent);
1787 
1788 }
#define PERR(format, args...)
Log a serious error.
Definition: qoflog.h:237
#define VREC
split is void
Definition: Split.h:71
#define YREC
The Split has been reconciled.
Definition: Split.h:68
#define FREC
frozen into accounting period
Definition: Split.h:69
void xaccAccountRecomputeBalance(Account *acc)
The following recompute the partial balances (stored with the transaction) and the total balance...
Definition: Account.c:2072
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1641
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1442
#define CREC
The Split has been cleared.
Definition: Split.h:67
#define NREC
not reconciled or cleared
Definition: Split.h:70

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

1189 {
1190  if (!s) return;
1191  ENTER (" ");
1192  xaccTransBeginEdit (s->parent);
1193 
1194  s->value = gnc_numeric_mul(xaccSplitGetAmount(s),
1195  price, get_currency_denom(s),
1197 
1198  SET_GAINS_VDIRTY(s);
1199  mark_split (s);
1200  qof_instance_set_dirty(QOF_INSTANCE(s));
1201  xaccTransCommitEdit(s->parent);
1202  LEAVE ("");
1203 }
#define ENTER(format, args...)
Print a function entry debugging message.
Definition: qoflog.h:261
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...
Definition: Transaction.c:1641
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1442
#define LEAVE(format, args...)
Print a function exit debugging message.
Definition: qoflog.h:271
gnc_numeric xaccSplitGetAmount(const Split *split)
Returns the amount of the split in the account&#39;s commodity.
Definition: Split.c:1926

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

1161 {
1162  if (!s) return;
1163  ENTER (" ");
1164  xaccTransBeginEdit (s->parent);
1165 
1166  s->amount = gnc_numeric_convert(amt, get_commodity_denom(s),
1168  s->value = gnc_numeric_mul(s->amount, price,
1169  get_currency_denom(s), GNC_HOW_RND_ROUND_HALF_UP);
1170 
1171  SET_GAINS_A_VDIRTY(s);
1172  mark_split (s);
1173  qof_instance_set_dirty(QOF_INSTANCE(s));
1174  xaccTransCommitEdit(s->parent);
1175  LEAVE ("");
1176 }
#define ENTER(format, args...)
Print a function entry debugging message.
Definition: qoflog.h:261
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...
Definition: Transaction.c:1641
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1442
#define LEAVE(format, args...)
Print a function exit debugging message.
Definition: qoflog.h:271

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

1259 {
1260  gnc_numeric new_val;
1261  if (!s) return;
1262 
1263  g_return_if_fail(gnc_numeric_check(amt) == GNC_ERROR_OK);
1264  ENTER ("(split=%p) old val=%" G_GINT64_FORMAT "/%" G_GINT64_FORMAT
1265  " new val=%" G_GINT64_FORMAT "/%" G_GINT64_FORMAT, s,
1266  s->value.num, s->value.denom, amt.num, amt.denom);
1267 
1268  xaccTransBeginEdit (s->parent);
1269  new_val = gnc_numeric_convert(amt, get_currency_denom(s),
1271  if (gnc_numeric_check(new_val) == GNC_ERROR_OK &&
1272  !(gnc_numeric_zero_p (new_val) && !gnc_numeric_zero_p (amt)))
1273  s->value = new_val;
1274  else PERR("numeric error %s in converting the split value's denominator with amount %s and denom %d", gnc_numeric_errorCode_to_string(gnc_numeric_check(new_val)), gnc_numeric_to_string(amt), get_currency_denom(s));
1275 
1276  SET_GAINS_VDIRTY(s);
1277  mark_split (s);
1278  qof_instance_set_dirty(QOF_INSTANCE(s));
1279  xaccTransCommitEdit(s->parent);
1280  LEAVE ("");
1281 }
gboolean gnc_numeric_zero_p(gnc_numeric a)
Returns 1 if the given gnc_numeric is 0 (zero), else returns 0.
gchar * gnc_numeric_to_string(gnc_numeric n)
Convert to string.
#define PERR(format, args...)
Log a serious error.
Definition: qoflog.h:237
#define ENTER(format, args...)
Print a function entry debugging message.
Definition: qoflog.h:261
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;...
const char * gnc_numeric_errorCode_to_string(GNCNumericErrorCode error_code)
Returns a string representation of the given GNCNumericErrorCode.
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1641
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1442
#define LEAVE(format, args...)
Print a function exit debugging message.
Definition: qoflog.h:271
GNCNumericErrorCode gnc_numeric_check(gnc_numeric in)
Check for error signal in value.
No error.
Definition: gnc-numeric.h:224

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

2143 {
2144  GValue v = G_VALUE_INIT;
2145  gnc_numeric *num = NULL;
2146  g_return_val_if_fail(split, gnc_numeric_zero());
2147  qof_instance_get_kvp (QOF_INSTANCE (split), void_former_amt_str, &v);
2148  if (G_VALUE_HOLDS_BOXED (&v))
2149  num = (gnc_numeric*)g_value_get_boxed (&v);
2150  return num ? *num : gnc_numeric_zero();
2151 }
void qof_instance_get_kvp(const QofInstance *inst, const gchar *key, GValue *value)
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 2154 of file Split.c.

2155 {
2156  GValue v = G_VALUE_INIT;
2157  gnc_numeric *num = NULL;
2158  g_return_val_if_fail(split, gnc_numeric_zero());
2159  qof_instance_get_kvp (QOF_INSTANCE (split), void_former_val_str, &v);
2160  if (G_VALUE_HOLDS_BOXED (&v))
2161  num = (gnc_numeric*)g_value_get_boxed (&v);
2162  return num ? *num : gnc_numeric_zero();
2163 }
void qof_instance_get_kvp(const QofInstance *inst, const gchar *key, GValue *value)
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 1442 of file Transaction.c.

1443 {
1444  if (!trans) return;
1445  if (!qof_begin_edit(&trans->inst)) return;
1446 
1447  if (qof_book_shutting_down(qof_instance_get_book(trans))) return;
1448 
1450  {
1451  xaccOpenLog ();
1452  xaccTransWriteLog (trans, 'B');
1453  }
1454 
1455  /* Make a clone of the transaction; we will use this
1456  * in case we need to roll-back the edit. */
1457  trans->orig = dupe_trans (trans);
1458 }
QofBook * qof_instance_get_book(gconstpointer inst)
Return the book pointer.
void xaccTransWriteLog(Transaction *trans, char flag)
Definition: TransLog.c:223
gboolean qof_begin_edit(QofInstance *inst)
begin_edit
gboolean qof_book_is_readonly(const QofBook *book)
Return whether the book is read only.
Definition: qofbook.cpp:584
gboolean qof_book_shutting_down(const QofBook *book)
Is the book shutting down?
Definition: qofbook.cpp:535

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

1642 {
1643  if (!trans) return;
1644  ENTER ("(trans=%p)", trans);
1645 
1646  if (!qof_commit_edit (QOF_INSTANCE(trans)))
1647  {
1648  LEAVE("editlevel non-zero");
1649  return;
1650  }
1651 
1652  /* We increment this for the duration of the call
1653  * so other functions don't result in a recursive
1654  * call to xaccTransCommitEdit. */
1655  qof_instance_increase_editlevel(trans);
1656 
1657  if (was_trans_emptied(trans))
1658  qof_instance_set_destroying(trans, TRUE);
1659 
1660  /* Before committing the transaction, we are going to enforce certain
1661  * constraints. In particular, we want to enforce the cap-gains
1662  * and the balanced lot constraints. These constraints might
1663  * change the number of splits in this transaction, and the
1664  * transaction itself might be deleted. This is also why
1665  * we can't really enforce these constraints elsewhere: they
1666  * can cause pointers to splits and transactions to disappear out
1667  * from under the holder.
1668  */
1669  if (!qof_instance_get_destroying(trans) && scrub_data &&
1671  {
1672  /* If scrubbing gains recurses through here, don't call it again. */
1673  scrub_data = 0;
1674  /* The total value of the transaction should sum to zero.
1675  * Call the trans scrub routine to fix it. Indirectly, this
1676  * routine also performs a number of other transaction fixes too.
1677  */
1678  xaccTransScrubImbalance (trans, NULL, NULL);
1679  /* Get the cap gains into a consistent state as well. */
1680 
1681  /* Lot Scrubbing is temporarily disabled. */
1682  if (g_getenv("GNC_AUTO_SCRUB_LOTS") != NULL)
1683  xaccTransScrubGains (trans, NULL);
1684 
1685  /* Allow scrubbing in transaction commit again */
1686  scrub_data = 1;
1687  }
1688 
1689  /* Record the time of last modification */
1690  if (0 == trans->date_entered.tv_sec)
1691  {
1692  trans->date_entered.tv_sec = gnc_time(NULL);
1693  qof_instance_set_dirty(QOF_INSTANCE(trans));
1694  }
1695 
1696  qof_commit_edit_part2(QOF_INSTANCE(trans),
1697  (void (*) (QofInstance *, QofBackendError))
1698  trans_on_error,
1699  (void (*) (QofInstance *)) trans_cleanup_commit,
1700  (void (*) (QofInstance *)) do_destroy);
1701  LEAVE ("(trans=%p)", trans);
1702 }
QofBackendError
The errors that can be reported to the GUI & other front-end users.
Definition: qofbackend.h:59
gboolean qof_instance_get_destroying(gconstpointer ptr)
Retrieve the flag that indicates whether or not this object is about to be destroyed.
gboolean qof_commit_edit(QofInstance *inst)
commit_edit helpers
#define ENTER(format, args...)
Print a function entry debugging message.
Definition: qoflog.h:261
void xaccTransScrubImbalance(Transaction *trans, Account *root, Account *account)
Correct transaction imbalances.
Definition: Scrub.c:797
void xaccTransScrubGains(Transaction *trans, Account *gain_acc)
The xaccTransScrubGains() routine performs a number of cleanup functions on the indicated transaction...
Definition: Transaction.c:2824
gboolean qof_commit_edit_part2(QofInstance *inst, void(*on_error)(QofInstance *, QofBackendError), void(*on_done)(QofInstance *), void(*on_free)(QofInstance *))
part2 – deal with the backend
#define xaccTransGetBook(X)
Definition: Transaction.h:768
#define LEAVE(format, args...)
Print a function exit debugging message.
Definition: qoflog.h:271
time64 gnc_time(time64 *tbuf)
get the current local time
Definition: gnc-date.cpp:251
gboolean qof_book_shutting_down(const QofBook *book)
Is the book shutting down?
Definition: qofbook.cpp:535

◆ xaccTransCopyFromClipBoard()

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

This function explicitly must robustly handle some unusual input.

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

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

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

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

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

Definition at line 745 of file Transaction.c.

747 {
748  Timespec ts = {0,0};
749  gboolean change_accounts = FALSE;
750  GList *node;
751 
752  if (!from_trans || !to_trans)
753  return;
754 
755  change_accounts = from_acc && GNC_IS_ACCOUNT(to_acc) && from_acc != to_acc;
756  xaccTransBeginEdit(to_trans);
757 
758  FOR_EACH_SPLIT(to_trans, xaccSplitDestroy(s));
759  g_list_free(to_trans->splits);
760  to_trans->splits = NULL;
761 
762  xaccTransSetCurrency(to_trans, xaccTransGetCurrency(from_trans));
763  xaccTransSetDescription(to_trans, xaccTransGetDescription(from_trans));
764 
765  if ((xaccTransGetNum(to_trans) == NULL) || (g_strcmp0 (xaccTransGetNum(to_trans), "") == 0))
766  xaccTransSetNum(to_trans, xaccTransGetNum(from_trans));
767 
768  xaccTransSetNotes(to_trans, xaccTransGetNotes(from_trans));
769  if(!no_date)
770  {
771  xaccTransGetDatePostedTS(from_trans, &ts);
772  xaccTransSetDatePostedTS(to_trans, &ts);
773  }
774 
775  /* Each new split will be parented to 'to' */
776  for (node = from_trans->splits; node; node = node->next)
777  {
778  Split *new_split = xaccMallocSplit( qof_instance_get_book(QOF_INSTANCE(from_trans)));
779  xaccSplitCopyOnto(node->data, new_split);
780  if (change_accounts && xaccSplitGetAccount(node->data) == from_acc)
781  xaccSplitSetAccount(new_split, to_acc);
782  xaccSplitSetParent(new_split, to_trans);
783  }
784  xaccTransCommitEdit(to_trans);
785 }
QofBook * qof_instance_get_book(gconstpointer inst)
Return the book pointer.
gboolean xaccSplitDestroy(Split *split)
Destructor.
Definition: Split.c:1456
void xaccTransSetNotes(Transaction *trans, const char *notes)
Sets the transaction Notes.
Definition: Transaction.c:2182
void xaccSplitCopyOnto(const Split *from_split, Split *to_split)
This is really a helper for xaccTransCopyOnto.
Definition: Split.c:650
void xaccTransSetDescription(Transaction *trans, const char *desc)
Sets the transaction Description.
Definition: Transaction.c:2150
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:2130
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:2275
void xaccTransSetCurrency(Transaction *trans, gnc_commodity *curr)
Set a new currency on a transaction.
Definition: Transaction.c:1413
const char * xaccTransGetNotes(const Transaction *trans)
Gets the transaction Notes.
Definition: Transaction.c:2298
const char * xaccTransGetDescription(const Transaction *trans)
Gets the transaction Description.
Definition: Transaction.c:2281
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1641
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1442
Split * xaccMallocSplit(QofBook *book)
Constructor.
Definition: Split.c:546
Account * xaccSplitGetAccount(const Split *s)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: Split.c:929
gnc_commodity * xaccTransGetCurrency(const Transaction *trans)
Returns the valuation commodity of this transaction.
Definition: Transaction.c:1354
void xaccTransGetDatePostedTS(const Transaction *trans, Timespec *ts)
Retrieve the posted date of the transaction.
Definition: Transaction.c:2337
void xaccTransSetDatePostedTS(Transaction *trans, const Timespec *ts)
The xaccTransSetDatePostedTS() method does the same thing as xaccTransSetDatePostedSecs(), but takes a struct timespec64.
Definition: Transaction.c:2021

◆ xaccTransCopyToClipBoard()

Transaction* xaccTransCopyToClipBoard ( const Transaction *  from_trans)

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

The 'clipboard' transaction must never be dereferenced.

Definition at line 705 of file Transaction.c.

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

◆ xaccTransCountSplits()

int xaccTransCountSplits ( const Transaction *  trans)

Returns the number of splits in this transaction.

Definition at line 2267 of file Transaction.c.

2268 {
2269  gint i = 0;
2270  FOR_EACH_SPLIT(trans, i++);
2271  return i;
2272 }

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

1465 {
1466  if (!trans) return;
1467 
1468  if (!xaccTransGetReadOnly (trans) ||
1470  {
1471  xaccTransBeginEdit(trans);
1472  qof_instance_set_destroying(trans, TRUE);
1473  xaccTransCommitEdit(trans);
1474  }
1475 }
QofBook * qof_instance_get_book(gconstpointer inst)
Return the book pointer.
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1641
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1442
const char * xaccTransGetReadOnly(const Transaction *trans)
Returns a non-NULL value if this Transaction was marked as read-only with some specific "reason" text...
Definition: Transaction.c:2422
gboolean qof_book_shutting_down(const QofBook *book)
Is the book shutting down?
Definition: qofbook.cpp:535

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

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

◆ xaccTransGetAccountAmount()

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

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

Definition at line 1192 of file Transaction.c.

1193 {
1194  gnc_numeric total = gnc_numeric_zero ();
1195  if (!trans || !acc) return total;
1196 
1197  total = gnc_numeric_convert (total, xaccAccountGetCommoditySCU (acc),
1199  FOR_EACH_SPLIT(trans, if (acc == xaccSplitGetAccount(s))
1200  total = gnc_numeric_add_fixed(
1201  total, xaccSplitGetAmount(s)));
1202  return total;
1203 }
int xaccAccountGetCommoditySCU(const Account *acc)
Return the SCU for the account.
Definition: Account.c:2455
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 *s)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: Split.c:929
gnc_numeric xaccSplitGetAmount(const Split *split)
Returns the amount of the split in the account&#39;s commodity.
Definition: Split.c:1926

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

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

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

1178 {
1179  gnc_numeric total = gnc_numeric_zero ();
1180  if (!trans || !acc) return total;
1181 
1182  FOR_EACH_SPLIT(trans, if (acc == xaccSplitGetAccount(s))
1183 {
1184  total = gnc_numeric_add (total, xaccSplitGetValue (s),
1187  });
1188  return total;
1189 }
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: Split.c:1932
Account * xaccSplitGetAccount(const Split *s)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: Split.c:929
#define GNC_DENOM_AUTO
Values that can be passed as the &#39;denom&#39; argument.
Definition: gnc-numeric.h:246

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

1355 {
1356  return trans ? trans->common_currency : NULL;
1357 }

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

2324 {
2325  return trans ? trans->date_posted.tv_sec : 0;
2326 }

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

2331 {
2332  return trans ? trans->date_entered.tv_sec : 0;
2333 }

◆ xaccTransGetDateEnteredTS()

void xaccTransGetDateEnteredTS ( const Transaction *  trans,
Timespec *  ts 
)

Retrieve the date of when the transaction was entered.

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

Definition at line 2344 of file Transaction.c.

2345 {
2346  if (trans && ts)
2347  *ts = trans->date_entered;
2348 }

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

2359 {
2360  GDate result;
2361  g_date_clear (&result, 1);
2362  if (trans)
2363  {
2364  /* Can we look up this value in the kvp slot? If yes, use it
2365  * from there because it doesn't suffer from time zone
2366  * shifts. */
2367  GValue v = G_VALUE_INIT;
2368  qof_instance_get_kvp (QOF_INSTANCE (trans), TRANS_DATE_POSTED, &v);
2369  if (G_VALUE_HOLDS_BOXED (&v))
2370  result = *(GDate*)g_value_get_boxed (&v);
2371  if (! g_date_valid (&result))
2373  }
2374  return result;
2375 }
void qof_instance_get_kvp(const QofInstance *inst, const gchar *key, GValue *value)
Retrieves the contents of a KVP slot into a provided GValue.
GDate timespec_to_gdate(Timespec ts)
Turns a Timespec into a GDate.
Definition: gnc-date.cpp:1330
Timespec xaccTransRetDatePostedTS(const Transaction *trans)
Retrieve the posted date of the transaction.
Definition: Transaction.c:2351

◆ xaccTransGetDatePostedTS()

void xaccTransGetDatePostedTS ( const Transaction *  trans,
Timespec *  ts 
)

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

2338 {
2339  if (trans && ts)
2340  *ts = trans->date_posted;
2341 }

◆ xaccTransGetFirstAPARAcctSplit()

Split* xaccTransGetFirstAPARAcctSplit ( const Transaction *  trans)

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

Parameters
transThe transaction

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

Definition at line 2255 of file Transaction.c.

2256 {
2257  FOR_EACH_SPLIT (trans,
2258  const Account *account = xaccSplitGetAccount(s);
2260  return s;
2261  );
2262 
2263  return NULL;
2264 }
GNCAccountType xaccAccountGetType(const Account *acc)
Returns the account&#39;s account type.
Definition: Account.c:3009
STRUCTS.
gboolean xaccAccountIsAPARType(GNCAccountType t)
Convenience function to check if the account is a valid business account type (meaning an Accounts Pa...
Definition: Account.c:4267
Account * xaccSplitGetAccount(const Split *s)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: Split.c:929

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

2245 {
2246  FOR_EACH_SPLIT (trans,
2247  const Account *account = xaccSplitGetAccount(s);
2249  return s;
2250  );
2251 
2252  return NULL;
2253 }
GNCAccountType xaccAccountGetType(const Account *acc)
Returns the account&#39;s account type.
Definition: Account.c:3009
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 *s)
Returns the account of this split, which was set through xaccAccountInsertSplit().
Definition: Split.c:929

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

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

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

1043 {
1044  gnc_numeric imbal = gnc_numeric_zero();
1045  if (!trans) return imbal;
1046 
1047  ENTER("(trans=%p)", trans);
1048  /* Could use xaccSplitsComputeValue, except that we want to use
1049  GNC_HOW_DENOM_EXACT */
1050  FOR_EACH_SPLIT(trans, imbal =
1053  LEAVE("(trans=%p) imbal=%s", trans, gnc_num_dbg_to_string(imbal));
1054  return imbal;
1055 }
gchar * gnc_num_dbg_to_string(gnc_numeric n)
Convert to string.
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
#define ENTER(format, args...)
Print a function entry debugging message.
Definition: qoflog.h:261
gnc_numeric xaccSplitGetValue(const Split *split)
Returns the value of this split in the transaction&#39;s commodity.
Definition: Split.c:1932
#define LEAVE(format, args...)
Print a function exit debugging message.
Definition: qoflog.h:271
#define GNC_DENOM_AUTO
Values that can be passed as the &#39;denom&#39; argument.
Definition: gnc-numeric.h:246

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

2299 {
2300  GValue v = G_VALUE_INIT;
2301  if (!trans) return NULL;
2302  qof_instance_get_kvp (QOF_INSTANCE (trans), trans_notes_str, &v);
2303  if (G_VALUE_HOLDS_STRING (&v))
2304  return g_value_get_string (&v);
2305  return NULL;
2306 }
void qof_instance_get_kvp(const QofInstance *inst, const gchar *key, GValue *value)
Retrieves the contents of a KVP slot into a provided GValue.

◆ xaccTransGetReadOnly()

const char* xaccTransGetReadOnly ( const Transaction *  trans)

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

Definition at line 2422 of file Transaction.c.

2423 {
2424  /* XXX This flag should be cached in the transaction structure
2425  * for performance reasons, since its checked every trans commit.
2426  */
2427  GValue v = G_VALUE_INIT;
2428  const char *s = NULL;
2429  if (trans == NULL) return NULL;
2430  qof_instance_get_kvp (QOF_INSTANCE(trans), TRANS_READ_ONLY_REASON, &v);
2431  if (G_VALUE_HOLDS_STRING (&v))
2432  s = g_value_get_string (&v);
2433  if (s && strlen (s))
2434  return s;
2435 
2436  return NULL;
2437 }
void qof_instance_get_kvp(const QofInstance *inst, const gchar *key, GValue *value)
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 2750 of file Transaction.c.

2751 {
2752  GValue v = G_VALUE_INIT;
2753  g_return_val_if_fail(trans, NULL);
2754  qof_instance_get_kvp (QOF_INSTANCE(trans), TRANS_REVERSED_BY, &v);
2755  if (G_VALUE_HOLDS_BOXED (&v))
2756  return xaccTransLookup((GncGUID*)g_value_get_boxed (&v),
2757  qof_instance_get_book(trans));
2758  return NULL;
2759 }
void qof_instance_get_kvp(const QofInstance *inst, const gchar *key, GValue *value)
Retrieves the contents of a KVP slot into a provided GValue.
QofBook * qof_instance_get_book(gconstpointer inst)
Return the book pointer.
Transaction * xaccTransLookup(const GncGUID *guid, QofBook *book)
The xaccTransLookup() subroutine will return the transaction associated with the given id...
Definition: Transaction.c:1030
The type used to store guids in C.
Definition: guid.h:75

◆ xaccTransGetSplit()

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

The xaccTransGetSplit() method returns a pointer to each of the splits in this transaction.

Parameters
transThe transaction
iThe split number. Valid values for i are zero to (number_of__splits-1). An invalid value of i will cause NULL to be returned. A convenient way of cycling through all splits is to start at zero, and keep incrementing until a null value is returned.

Definition at line 2219 of file Transaction.c.

2220 {
2221  int j = 0;
2222  if (!trans || i < 0) return NULL;
2223 
2224  FOR_EACH_SPLIT(trans, { if (i == j) return s; j++; });
2225  return NULL;
2226 }

◆ xaccTransGetSplitList()

SplitList* xaccTransGetSplitList ( const Transaction *  trans)

The xaccTransGetSplitList() method returns a GList of the splits in a 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 2239 of file Transaction.c.

2240 {
2241  return trans ? trans->splits : NULL;
2242 }

◆ xaccTransGetTxnType()

char xaccTransGetTxnType ( const Transaction *  trans)

Returns the Transaction Type.

See TXN_TYPE_NONE, TXN_TYPE_INVOICE and TXN_TYPE_PAYMENT

Definition at line 2406 of file Transaction.c.

2407 {
2408  const char *s = NULL;
2409  GValue v = G_VALUE_INIT;
2410 
2411  if (!trans) return TXN_TYPE_NONE;
2412  qof_instance_get_kvp (QOF_INSTANCE (trans), TRANS_TXN_TYPE_KVP, &v);
2413  if (G_VALUE_HOLDS_STRING (&v))
2414  s = g_value_get_string (&v);
2415  if (s && strlen (s) == 1)
2416  return *s;
2417 
2418  return TXN_TYPE_NONE;
2419 }
void qof_instance_get_kvp(const QofInstance *inst, const gchar *key, GValue *value)
Retrieves the contents of a KVP slot into a provided GValue.
#define TXN_TYPE_NONE
No transaction type.
Definition: Transaction.h:119

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

2665 {
2666  GValue v = G_VALUE_INIT;
2667  g_return_val_if_fail(trans, FALSE);
2668 
2669  qof_instance_get_kvp (QOF_INSTANCE (trans), void_reason_str, &v);
2670  if (G_VALUE_HOLDS_STRING (&v))
2671  return g_value_get_string (&v);
2672  return NULL;
2673 }
void qof_instance_get_kvp(const QofInstance *inst, const gchar *key, GValue *value)
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 2651 of file Transaction.c.

2652 {
2653  const char *s = NULL;
2654  GValue v = G_VALUE_INIT;
2655  g_return_val_if_fail(trans, FALSE);
2656 
2657  qof_instance_get_kvp (QOF_INSTANCE (trans), void_reason_str, &v);
2658  if (G_VALUE_HOLDS_STRING (&v))
2659  s = g_value_get_string (&v);
2660  return s && strlen(s);
2661 }
void qof_instance_get_kvp(const QofInstance *inst, const gchar *key, GValue *value)
Retrieves the contents of a KVP slot into a provided GValue.

◆ xaccTransGetVoidTime()

Timespec xaccTransGetVoidTime ( const Transaction *  tr)

Returns the time that a transaction was voided.

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

Definition at line 2676 of file Transaction.c.

2677 {
2678  GValue v = G_VALUE_INIT;
2679  const char *s = NULL;
2680  Timespec void_time = {0, 0};
2681 
2682  g_return_val_if_fail(tr, void_time);
2683  qof_instance_get_kvp (QOF_INSTANCE (tr), void_time_str, &v);
2684  if (G_VALUE_HOLDS_STRING (&v))
2685  s = g_value_get_string (&v);
2686  if (s)
2687  return gnc_iso8601_to_timespec_gmt (s);
2688  return void_time;
2689 }
void qof_instance_get_kvp(const QofInstance *inst, const gchar *key, GValue *value)
Retrieves the contents of a KVP slot into a provided GValue.
Timespec gnc_iso8601_to_timespec_gmt(const gchar *)
The gnc_iso8601_to_timespec_gmt() routine converts an ISO-8601 style date/time string to Timespec...

◆ xaccTransIsBalanced()

gboolean xaccTransIsBalanced ( const Transaction *  trans)

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

Definition at line 1130 of file Transaction.c.

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

1874 {
1875  return trans ? (0 < qof_instance_get_editlevel(trans)) : FALSE;
1876 }

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

2463 {
2464  GDate *threshold_date;
2465  GDate trans_date;
2466  const QofBook *book = xaccTransGetBook (trans);
2467  gboolean result;
2468  g_assert(trans);
2469 
2470  if (!qof_book_uses_autoreadonly(book))
2471  {
2472  return FALSE;
2473  }
2474 
2475  if (xaccTransIsSXTemplate (trans))
2476  return FALSE;
2477 
2478  threshold_date = qof_book_get_autoreadonly_gdate(book);
2479  g_assert(threshold_date); // ok because we checked uses_autoreadonly before
2480  trans_date = xaccTransGetDatePostedGDate(trans);
2481 
2482 // g_warning("there is auto-read-only with days=%d, trans_date_day=%d, threshold_date_day=%d",
2483 // qof_book_get_num_days_autofreeze(book),
2484 // g_date_get_day(&trans_date),
2485 // g_date_get_day(threshold_date));
2486 
2487  if (g_date_compare(&trans_date, threshold_date) < 0)
2488  {
2489  //g_warning("we are auto-read-only");
2490  result = TRUE;
2491  }
2492  else
2493  {
2494  result = FALSE;
2495  }
2496  g_date_free(threshold_date);
2497  return result;
2498 }
GDate * qof_book_get_autoreadonly_gdate(const QofBook *book)
Returns the GDate that is the threshold for auto-read-only.
Definition: qofbook.cpp:1070
#define xaccTransGetBook(X)
Definition: Transaction.h:768
gboolean qof_book_uses_autoreadonly(const QofBook *book)
Returns TRUE if the auto-read-only feature should be used, otherwise FALSE.
Definition: qofbook.cpp:1054
GDate xaccTransGetDatePostedGDate(const Transaction *trans)
Retrieve the posted date of the transaction.
Definition: Transaction.c:2358

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

1031 {
1032  QofCollection *col;
1033  if (!guid || !book) return NULL;
1034  col = qof_book_get_collection (book, GNC_ID_TRANS);
1035  return (Transaction *) qof_collection_lookup_entity (col, guid);
1036 }
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:599

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

1882 {
1883  return xaccTransOrder_num_action (ta, NULL, tb, NULL);
1884 }
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:1887

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

1889 {
1890  char *da, *db;
1891  int na, nb, retval;
1892 
1893  if ( ta && !tb ) return -1;
1894  if ( !ta && tb ) return +1;
1895  if ( !ta && !tb ) return 0;
1896 
1897  /* if dates differ, return */
1898  DATE_CMP(ta, tb, date_posted);
1899 
1900  /* otherwise, sort on number string */
1901  if (actna && actnb) /* split action string, if not NULL */
1902  {
1903  na = atoi(actna);
1904  nb = atoi(actnb);
1905  }
1906  else /* else transaction num string */
1907  {
1908  na = atoi(ta->num);
1909  nb = atoi(tb->num);
1910  }
1911  if (na < nb) return -1;
1912  if (na > nb) return +1;
1913 
1914  /* if dates differ, return */
1915  DATE_CMP(ta, tb, date_entered);
1916 
1917  /* otherwise, sort on description string */
1918  da = ta->description ? ta->description : "";
1919  db = tb->description ? tb->description : "";
1920  retval = g_utf8_collate (da, db);
1921  if (retval)
1922  return retval;
1923 
1924  /* else, sort on guid - keeps sort stable. */
1925  return qof_instance_guid_compare(ta, tb);
1926 }
gint qof_instance_guid_compare(gconstpointer ptr1, gconstpointer ptr2)
Compare the GncGUID values of two instances.

◆ xaccTransRetDateEnteredTS()

Timespec xaccTransRetDateEnteredTS ( 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 2378 of file Transaction.c.

2379 {
2380  Timespec ts = {0, 0};
2381  return trans ? trans->date_entered : ts;
2382 }

◆ xaccTransRetDatePostedTS()

Timespec xaccTransRetDatePostedTS ( 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 2351 of file Transaction.c.

2352 {
2353  Timespec ts = {0, 0};
2354  return trans ? trans->date_posted : ts;
2355 }

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

2720 {
2721  Transaction *trans;
2722  GValue v = G_VALUE_INIT;
2723  g_return_val_if_fail(orig, NULL);
2724 
2725  trans = xaccTransClone(orig);
2726  xaccTransBeginEdit(trans);
2727 
2728  /* Reverse the values on each split. Clear per-split info. */
2729  FOR_EACH_SPLIT(trans,
2730  {
2734  });
2735 
2736  /* Now update the original with a pointer to the new one */
2737  g_value_init (&v, GNC_TYPE_GUID);
2738  g_value_set_boxed (&v, xaccTransGetGUID(trans));
2739  qof_instance_set_kvp (QOF_INSTANCE (orig), TRANS_REVERSED_BY, &v);
2740 
2741  /* Make sure the reverse transaction is not read-only */
2742  xaccTransClearReadOnly(trans);
2743 
2744  qof_instance_set_dirty(QOF_INSTANCE(trans));
2745  xaccTransCommitEdit(trans);
2746  return trans;
2747 }
void xaccSplitSetValue(Split *s, gnc_numeric amt)
The xaccSplitSetValue() method sets the value of this split in the transaction&#39;s commodity.
Definition: Split.c:1258
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.
Definition: Split.c:1765
void xaccSplitSetAmount(Split *s, gnc_numeric amt)
The xaccSplitSetAmount() method sets the amount in the account&#39;s commodity that the split should have...
Definition: Split.c:1222
Transaction * xaccTransClone(const Transaction *from)
The xaccTransClone() method will create a complete copy of an existing transaction.
Definition: Transaction.c:682
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1641
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1442
#define xaccTransGetGUID(X)
Definition: Transaction.h:770
gnc_numeric xaccSplitGetValue(const Split *split)
Returns the value of this split in the transaction&#39;s commodity.
Definition: Split.c:1932
void qof_instance_set_kvp(QofInstance *inst, const gchar *key, const GValue *value)
Sets a KVP slot to a value from a GValue.
#define NREC
not reconciled or cleared
Definition: Split.h:70
gnc_numeric xaccSplitGetAmount(const Split *split)
Returns the amount of the split in the account&#39;s commodity.
Definition: Split.c:1926

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

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

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

2825 {
2826  SplitList *node;
2827 
2828  ENTER("(trans=%p)", trans);
2829  /* Lock down posted date, its to be synced to the posted date
2830  * for the source of the cap gains. */
2831  xaccTransScrubGainsDate(trans);
2832 
2833  /* Fix up the split amount */
2834 restart:
2835  for (node = trans->splits; node; node = node->next)
2836  {
2837  Split *s = node->data;
2838 
2839  if (!xaccTransStillHasSplit(trans, s)) continue;
2840 
2841  xaccSplitDetermineGainStatus(s);
2842  if (s->gains & GAINS_STATUS_ADIRTY)
2843  {
2844  gboolean altered = FALSE;
2845  s->gains &= ~GAINS_STATUS_ADIRTY;
2846  if (s->lot)
2847  altered = xaccScrubLot(s->lot);
2848  else
2849  altered = xaccSplitAssign(s);
2850  if (altered) goto restart;
2851  }
2852  }
2853 
2854  /* Fix up gains split value */
2855  FOR_EACH_SPLIT(trans,
2856  if ((s->gains & GAINS_STATUS_VDIRTY) ||
2857  (s->gains_split &&
2858  (s->gains_split->gains & GAINS_STATUS_VDIRTY)))
2859  xaccSplitComputeCapGains(s, gain_acc);
2860  );
2861 
2862  LEAVE("(trans=%p)", trans);
2863 }
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:261
GList SplitList
GList of Split.
Definition: gnc-engine.h:203
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:430
#define LEAVE(format, args...)
Print a function exit debugging message.
Definition: qoflog.h:271
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 1413 of file Transaction.c.

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

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

2047 {
2048  GDate *date;
2049  if (!trans) return;
2050  date = g_date_new_dmy(day, mon, year);
2051  if (!g_date_valid(date))
2052  {
2053  PWARN("Attempted to set invalid date %d-%d-%d; set today's date instead.",
2054  year, mon, day);
2055  g_free(date);
2056  date = gnc_g_date_new_today();
2057  }
2058  xaccTransSetDatePostedGDate(trans, *date);
2059  g_free(date);
2060 }
void xaccTransSetDatePostedGDate(Transaction *trans, GDate date)
This method modifies posted date of the transaction, specified by a GDate.
Definition: Transaction.c:1984
#define PWARN(format, args...)
Log a warning.
Definition: qoflog.h:243
GDate * gnc_g_date_new_today()
Returns a newly allocated date of the current clock time, taken from time(2).
Definition: gnc-date.cpp:1344

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

2003 {
2004  Timespec ts = {secs, 0};
2005  if (!trans) return;
2006  xaccTransSetDateInternal(trans, &trans->date_entered, ts);
2007 }

◆ xaccTransSetDateEnteredTS()

void xaccTransSetDateEnteredTS ( Transaction *  trans,
const Timespec *  ts 
)

Modify the date of when the transaction was entered.

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

Definition at line 2039 of file Transaction.c.

2040 {
2041  if (!trans || !ts) return;
2042  xaccTransSetDateInternal(trans, &trans->date_entered, *ts);
2043 }

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

1985 {
1986  GValue v = G_VALUE_INIT;
1987  if (!trans) return;
1988 
1989  /* We additionally save this date into a kvp frame to ensure in
1990  * the future a date which was set as *date* (without time) can
1991  * clearly be distinguished from the Timespec. */
1992  g_value_init (&v, G_TYPE_DATE);
1993  g_value_set_boxed (&v, &date);
1994  qof_instance_set_kvp (QOF_INSTANCE(trans), TRANS_DATE_POSTED, &v);
1995  /* mark dirty and commit handled by SetDateInternal */
1996  xaccTransSetDateInternal(trans, &trans->date_posted,
1997  gdate_to_timespec(date));
1998  set_gains_date_dirty (trans);
1999 }
Timespec gdate_to_timespec(GDate d)
Turns a GDate into a Timespec, returning the first second of the day.
Definition: gnc-date.cpp:1371
void qof_instance_set_kvp(QofInstance *inst, const gchar *key, const GValue *value)
Sets a KVP slot to a value from a GValue.

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

1968 {
1969  Timespec ts = {secs, 0};
1970  if (!trans) return;
1971  xaccTransSetDateInternal(trans, &trans->date_posted, ts);
1972  set_gains_date_dirty (trans);
1973 }

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

1977 {
1978  GDate date;
1979  gnc_gdate_set_time64(&date, time);
1980  xaccTransSetDatePostedGDate(trans, date);
1981 }
void xaccTransSetDatePostedGDate(Transaction *trans, GDate date)
This method modifies posted date of the transaction, specified by a GDate.
Definition: Transaction.c:1984
void gnc_gdate_set_time64(GDate *gd, time64 time)
Set a GDate to a time64.
Definition: gnc-date.cpp:1362

◆ xaccTransSetDatePostedTS()

void xaccTransSetDatePostedTS ( Transaction *  trans,
const Timespec *  ts 
)

The xaccTransSetDatePostedTS() method does the same thing as xaccTransSetDatePostedSecs(), but takes a struct timespec64.

Definition at line 2021 of file Transaction.c.

2022 {
2023  if (!trans || !ts) return;
2024  xaccTransSetDateInternal(trans, &trans->date_posted, *ts);
2025  set_gains_date_dirty (trans);
2026 }

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

2183 {
2184  GValue v = G_VALUE_INIT;
2185  if (!trans || !notes) return;
2186  g_value_init (&v, G_TYPE_STRING);
2187  g_value_set_string (&v, notes);
2188  xaccTransBeginEdit(trans);
2189 
2190  qof_instance_set_kvp (QOF_INSTANCE (trans), trans_notes_str, &v);
2191  qof_instance_set_dirty(QOF_INSTANCE(trans));
2192  xaccTransCommitEdit(trans);
2193 }
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1641
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1442
void qof_instance_set_kvp(QofInstance *inst, const gchar *key, const GValue *value)
Sets a KVP slot to a value from a GValue.

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

2103 {
2104  if (trans && reason)
2105  {
2106  GValue v = G_VALUE_INIT;
2107  g_value_init (&v, G_TYPE_STRING);
2108  g_value_set_string (&v, reason);
2109  xaccTransBeginEdit(trans);
2110  qof_instance_set_kvp (QOF_INSTANCE (trans), TRANS_READ_ONLY_REASON, &v);
2111  qof_instance_set_dirty(QOF_INSTANCE(trans));
2112  xaccTransCommitEdit(trans);
2113  }
2114 }
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1641
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1442
void qof_instance_set_kvp(QofInstance *inst, const gchar *key, const GValue *value)
Sets a KVP slot to a value from a GValue.

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

2077 {
2078  char s[2] = {type, '\0'};
2079  GValue v = G_VALUE_INIT;
2080  g_return_if_fail(trans);
2081  g_value_init (&v, G_TYPE_STRING);
2082  g_value_set_string (&v, s);
2083  xaccTransBeginEdit(trans);
2084  qof_instance_set_kvp (QOF_INSTANCE (trans), TRANS_TXN_TYPE_KVP, &v);
2085  qof_instance_set_dirty(QOF_INSTANCE(trans));
2086  xaccTransCommitEdit(trans);
2087 }
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1641
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1442
void qof_instance_set_kvp(QofInstance *inst, const gchar *key, const GValue *value)
Sets a KVP slot to a value from a GValue.

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

2693 {
2694  GValue v = G_VALUE_INIT;
2695  const char *s = NULL;
2696  g_return_if_fail(trans);
2697 
2698  qof_instance_get_kvp (QOF_INSTANCE (trans), void_reason_str, &v);
2699  if (G_VALUE_HOLDS_STRING (&v))
2700  s = g_value_get_string (&v);
2701  if (s == NULL) return; /* Transaction isn't voided. Bail. */
2702  xaccTransBeginEdit(trans);
2703 
2704  qof_instance_get_kvp (QOF_INSTANCE (trans), void_former_notes_str, &v);
2705  if (G_VALUE_HOLDS_STRING (&v))
2706  qof_instance_set_kvp (QOF_INSTANCE (trans), trans_notes_str, &v);
2707  qof_instance_set_kvp (QOF_INSTANCE (trans), void_former_notes_str, NULL);
2708  qof_instance_set_kvp (QOF_INSTANCE (trans), void_reason_str, NULL);
2709  qof_instance_set_kvp (QOF_INSTANCE (trans), void_time_str, NULL);
2710 
2711  FOR_EACH_SPLIT(trans, xaccSplitUnvoid(s));
2712 
2713  /* Dirtying taken care of by ClearReadOnly */
2714  xaccTransClearReadOnly(trans);
2715  xaccTransCommitEdit(trans);
2716 }
void qof_instance_get_kvp(const QofInstance *inst, const gchar *key, GValue *value)
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:1641
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1442
void qof_instance_set_kvp(QofInstance *inst, const gchar *key, const GValue *value)
Sets a KVP slot to a value from a GValue.

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

2613 {
2614  GValue v = G_VALUE_INIT;
2615  char iso8601_str[ISO_DATELENGTH + 1] = "";
2616 
2617  g_return_if_fail(trans && reason);
2618 
2619  /* Prevent voiding transactions that are already marked
2620  * read only, for example generated by the business features.
2621  */
2622  if (xaccTransGetReadOnly (trans))
2623  {
2624  PWARN ("Refusing to void a read-only transaction!");
2625  return;
2626  }
2627  xaccTransBeginEdit(trans);
2628  qof_instance_get_kvp (QOF_INSTANCE (trans), trans_notes_str, &v);
2629  if (G_VALUE_HOLDS_STRING (&v))
2630  qof_instance_set_kvp (QOF_INSTANCE (trans), void_former_notes_str, &v);
2631  else
2632  g_value_init (&v, G_TYPE_STRING);
2633 
2634  g_value_set_string (&v, _("Voided transaction"));
2635  qof_instance_set_kvp (QOF_INSTANCE (trans), trans_notes_str, &v);
2636  g_value_set_string (&v, reason);
2637  qof_instance_set_kvp (QOF_INSTANCE (trans), void_reason_str, &v);
2638 
2639  gnc_timespec_to_iso8601_buff (timespec_now (), iso8601_str);
2640  g_value_set_string (&v, iso8601_str);
2641  qof_instance_set_kvp (QOF_INSTANCE (trans), void_time_str, &v);
2642 
2643  FOR_EACH_SPLIT(trans, xaccSplitVoid(s));
2644 
2645  /* Dirtying taken care of by SetReadOnly */
2646  xaccTransSetReadOnly(trans, _("Transaction Voided"));
2647  xaccTransCommitEdit(trans);
2648 }
void qof_instance_get_kvp(const QofInstance *inst, const gchar *key, GValue *value)
Retrieves the contents of a KVP slot into a provided GValue.
gchar * gnc_timespec_to_iso8601_buff(Timespec ts, gchar *buff)
The gnc_timespec_to_iso8601_buff() routine takes the input UTC Timespec value and prints it as an ISO...
#define PWARN(format, args...)
Log a warning.
Definition: qoflog.h:243
void xaccTransSetReadOnly(Transaction *trans, const char *reason)
Set the transaction to be ReadOnly by setting a non-NULL value as "reason".
Definition: Transaction.c:2102
void xaccTransCommitEdit(Transaction *trans)
The xaccTransCommitEdit() method indicates that the changes to the transaction and its splits are com...
Definition: Transaction.c:1641
void xaccTransBeginEdit(Transaction *trans)
The xaccTransBeginEdit() method must be called before any changes are made to a transaction or any of...
Definition: Transaction.c:1442
const char * xaccTransGetReadOnly(const Transaction *trans)
Returns a non-NULL value if this Transaction was marked as read-only with some specific "reason" text...
Definition: Transaction.c:2422
Timespec timespec_now()
Returns the current clock time as a Timespec, taken from time(2).
Definition: gnc-date.cpp:1312
void qof_instance_set_kvp(QofInstance *inst, const gchar *key, const GValue *value)
Sets a KVP slot to a value from a GValue.