GnuCash  2.6.18
Data Structures | Macros | Typedefs | Enumerations | Functions

Account handling public routines. More...

#include "qof.h"
#include "gnc-engine.h"
#include "policy.h"

Go to the source code of this file.

Data Structures

struct  AccountClass


#define GNC_TYPE_ACCOUNT   (gnc_account_get_type ())
#define xaccAccountGetSlots(X)   qof_instance_get_slots(QOF_INSTANCE(X))
#define ACCOUNT_MATCH_ALL_TYPE   "account-match-all"
Account parameter names
#define ACCOUNT_KVP   "kvp"
#define ACCOUNT_NAME_   "name"
#define ACCOUNT_CODE_   "code"
#define ACCOUNT_DESCRIPTION_   "desc"
#define ACCOUNT_COLOR_   "color"
#define ACCOUNT_FILTER_   "filter"
#define ACCOUNT_SORT_ORDER_   "sort-order"
#define ACCOUNT_SORT_REVERSED_   "sort-reversed"
#define ACCOUNT_NOTES_   "notes"
#define ACCOUNT_BALANCE_   "balance"
#define ACCOUNT_CLEARED_   "cleared"
#define ACCOUNT_RECONCILED_   "reconciled"
#define ACCOUNT_PRESENT_   "present"
#define ACCOUNT_FUTURE_MINIMUM_   "future-minimum"
#define ACCOUNT_TAX_RELATED   "tax-related-p"
#define ACCOUNT_TYPE_   "account-type"
#define ACCOUNT_SCU   "smallest-commodity-unit"
#define ACCOUNT_NSCU   "non-standard-scu"
#define ACCOUNT_PARENT   "parent-account"


typedef gnc_numeric(* xaccGetBalanceFn) (const Account *account)
typedef gnc_numeric(* xaccGetBalanceInCurrencyFn) (const Account *account, const gnc_commodity *report_commodity, gboolean include_children)
typedef gnc_numeric(* xaccGetBalanceAsOfDateFn) (Account *account, time64 date)
typedef void(* AccountCb) (Account *a, gpointer data)
typedef gpointer(* AccountCb2) (Account *a, gpointer data)


enum  GNCAccountType {


GType gnc_account_get_type (void)
gchar * gnc_account_name_violations_errmsg (const gchar *separator, GList *invalid_account_names)
GList * gnc_account_list_name_violations (QofBook *book, const gchar *separator)
void xaccAccountSetReconcileChildrenStatus (Account *account, gboolean status)
gboolean xaccAccountGetReconcileChildrenStatus (const Account *account)
gboolean xaccAccountHasAncestor (const Account *acc, const Account *ancestor)
Account Constructors, Edit/Commit, Comparison
AccountxaccMallocAccount (QofBook *book)
Accountgnc_account_create_root (QofBook *book)
AccountxaccCloneAccount (const Account *source, QofBook *book)
void xaccAccountBeginEdit (Account *account)
void xaccAccountCommitEdit (Account *account)
void xaccAccountDestroy (Account *account)
gboolean xaccAccountEqual (const Account *a, const Account *b, gboolean check_guids)
int xaccAccountOrder (const Account *account_1, const Account *account_2)
Account general setters/getters
QofBook * gnc_account_get_book (const Account *account)
void xaccAccountSetType (Account *account, GNCAccountType)
void xaccAccountSetName (Account *account, const char *name)
void xaccAccountSetCode (Account *account, const char *code)
void xaccAccountSetDescription (Account *account, const char *desc)
void xaccAccountSetColor (Account *account, const char *color)
void xaccAccountSetFilter (Account *account, const char *filter)
void xaccAccountSetSortOrder (Account *account, const char *sortorder)
void xaccAccountSetSortReversed (Account *account, gboolean sortreversed)
void xaccAccountSetNotes (Account *account, const char *notes)
void xaccAccountSetLastNum (Account *account, const char *num)
void gnc_account_set_policy (Account *account, GNCPolicy *policy)
GNCAccountType xaccAccountGetType (const Account *account)
gboolean xaccAccountIsPriced (const Account *acc)
void gnc_account_set_start_balance (Account *acc, const gnc_numeric start_baln)
void gnc_account_set_start_cleared_balance (Account *acc, const gnc_numeric start_baln)
void gnc_account_set_start_reconciled_balance (Account *acc, const gnc_numeric start_baln)
void gnc_account_set_balance_dirty (Account *acc)
void gnc_account_set_sort_dirty (Account *acc)
gboolean gnc_account_insert_split (Account *acc, Split *s)
gboolean gnc_account_remove_split (Account *acc, Split *s)
const char * xaccAccountGetName (const Account *account)
const char * xaccAccountGetCode (const Account *account)
const char * xaccAccountGetDescription (const Account *account)
const char * xaccAccountGetColor (const Account *account)
const char * xaccAccountGetFilter (const Account *account)
const char * xaccAccountGetSortOrder (const Account *account)
gboolean xaccAccountGetSortReversed (const Account *account)
const char * xaccAccountGetNotes (const Account *account)
const char * xaccAccountGetLastNum (const Account *account)
GNCPolicy * gnc_account_get_policy (Account *account)
void xaccAccountRecomputeBalance (Account *)
void xaccAccountSortSplits (Account *acc, gboolean force)
gchar * gnc_account_get_full_name (const Account *account)
void dxaccAccountSetPriceSrc (Account *account, const char *src)
const char * dxaccAccountGetPriceSrc (const Account *account)
gboolean xaccAccountGetAutoInterestXfer (const Account *account, gboolean default_value)
void xaccAccountSetAutoInterestXfer (Account *account, gboolean value)
Account Commodity setters/getters

Accounts are used to store an amount of 'something', that 'something' is called the 'commodity'. An account can only hold one kind of commodity. The following are used to get and set the commodity, and also to set the SCU, the 'Smallest Commodity Unit'.

Note that when we say that a 'split' holds an 'amount', that amount is denominated in the account commodity. Do not confuse 'amount' and 'value'. The 'value' of a split is the value of the amount expressed in the currency of the transaction. Thus, for example, the 'amount' may be 12 apples, where the account commodity is 'apples'. The value of these 12 apples may be 12 dollars, where the transaction currency is 'dollars'.

The SCU is the 'Smallest Commodity Unit', signifying the smallest non-zero amount that can be stored in the account. It is represented as the integer denominator of a fraction. Thus, for example, a SCU of 12 means that 1/12 of something is the smallest amount that can be stored in the account. SCU's can be any value; they do not need to be decimal. This allows the use of accounts with unusual, non-decimal commodities and currencies.

Normally, the SCU is determined by the commodity of the account. However, this default SCU can be over-ridden and set to an account-specific value. This is account-specific value is called the 'non-standard' value in the documentation below.

void xaccAccountSetCommodity (Account *account, gnc_commodity *comm)
gnc_commodity * xaccAccountGetCommodity (const Account *account)
gnc_commodity * gnc_account_get_currency_or_parent (const Account *account)
int xaccAccountGetCommoditySCU (const Account *account)
int xaccAccountGetCommoditySCUi (const Account *account)
void xaccAccountSetCommoditySCU (Account *account, int frac)
void xaccAccountSetNonStdSCU (Account *account, gboolean flag)
gboolean xaccAccountGetNonStdSCU (const Account *account)
Account Balance
gnc_numeric xaccAccountGetBalance (const Account *account)
gnc_numeric xaccAccountGetClearedBalance (const Account *account)
gnc_numeric xaccAccountGetReconciledBalance (const Account *account)
gnc_numeric xaccAccountGetPresentBalance (const Account *account)
gnc_numeric xaccAccountGetProjectedMinimumBalance (const Account *account)
gnc_numeric xaccAccountGetBalanceAsOfDate (Account *account, time64 date)
gnc_numeric xaccAccountConvertBalanceToCurrency (const Account *account, gnc_numeric balance, const gnc_commodity *balance_currency, const gnc_commodity *new_currency)
gnc_numeric xaccAccountConvertBalanceToCurrencyAsOfDate (const Account *account, gnc_numeric balance, gnc_commodity *balance_currency, gnc_commodity *new_currency, time64 date)
gnc_numeric xaccAccountGetBalanceInCurrency (const Account *account, const gnc_commodity *report_commodity, gboolean include_children)
gnc_numeric xaccAccountGetClearedBalanceInCurrency (const Account *account, const gnc_commodity *report_commodity, gboolean include_children)
gnc_numeric xaccAccountGetReconciledBalanceInCurrency (const Account *account, const gnc_commodity *report_commodity, gboolean include_children)
gnc_numeric xaccAccountGetPresentBalanceInCurrency (const Account *account, const gnc_commodity *report_commodity, gboolean include_children)
gnc_numeric xaccAccountGetProjectedMinimumBalanceInCurrency (const Account *account, const gnc_commodity *report_commodity, gboolean include_children)
gnc_numeric xaccAccountGetBalanceAsOfDateInCurrency (Account *account, time64 date, gnc_commodity *report_commodity, gboolean include_children)
gnc_numeric xaccAccountGetBalanceChangeForPeriod (Account *acc, time64 date1, time64 date2, gboolean recurse)
Account Children and Parents.

The set of accounts is represented as a doubly-linked tree, so that given any account, both its parent and its children can be easily found. At the top of the tree hierarchy lies a single root node, the root account.

The account tree hierarchy is unique, in that a given account can have only one parent account.

void gnc_account_append_child (Account *new_parent, Account *child)
void gnc_account_remove_child (Account *parent, Account *child)
Accountgnc_account_get_parent (const Account *account)
Accountgnc_account_get_root (Account *account)
gboolean gnc_account_is_root (const Account *account)
GList * gnc_account_get_children (const Account *account)
GList * gnc_account_get_children_sorted (const Account *account)
gint gnc_account_n_children (const Account *account)
gint gnc_account_child_index (const Account *parent, const Account *child)
Accountgnc_account_nth_child (const Account *parent, gint num)
GList * gnc_account_get_descendants (const Account *account)
GList * gnc_account_get_descendants_sorted (const Account *account)
gint gnc_account_n_descendants (const Account *account)
gint gnc_account_get_current_depth (const Account *account)
gint gnc_account_get_tree_depth (const Account *account)
void gnc_account_foreach_child (const Account *account, AccountCb func, gpointer user_data)
void gnc_account_foreach_descendant (const Account *account, AccountCb func, gpointer user_data)
gpointer gnc_account_foreach_descendant_until (const Account *account, AccountCb2 func, gpointer user_data)
Concatenation, Merging
void gnc_account_join_children (Account *to_parent, Account *from_parent)
void gnc_account_merge_children (Account *parent)
Lookup Accounts and Subaccounts by name or code
Accountgnc_account_lookup_by_name (const Account *parent, const char *name)
Accountgnc_account_lookup_by_full_name (const Account *any_account, const gchar *name)
Accountgnc_account_lookup_by_code (const Account *parent, const char *code)
GNCAccountType conversion/checking
const char * xaccAccountTypeEnumAsString (GNCAccountType type)
gboolean xaccAccountStringToType (const char *str, GNCAccountType *type)
GNCAccountType xaccAccountStringToEnum (const char *str)
const char * xaccAccountGetTypeStr (GNCAccountType type)
guint32 xaccAccountTypesCompatibleWith (GNCAccountType type)
guint32 xaccParentAccountTypesCompatibleWith (GNCAccountType type)
gboolean xaccAccountTypesCompatible (GNCAccountType parent_type, GNCAccountType child_type)
guint32 xaccAccountTypesValid (void)
gboolean xaccAccountIsAssetLiabType (GNCAccountType t)
gboolean xaccAccountIsAPARType (GNCAccountType t)
gboolean xaccAccountIsEquityType (GNCAccountType t)
Account lots
void xaccAccountInsertLot (Account *, GNCLot *)
void xaccAccountRemoveLot (Account *, GNCLot *)
LotListxaccAccountGetLotList (const Account *account)
gpointer xaccAccountForEachLot (const Account *acc, gpointer(*proc)(GNCLot *lot, gpointer user_data), gpointer user_data)
LotListxaccAccountFindOpenLots (const Account *acc, gboolean(*match_func)(GNCLot *lot, gpointer user_data), gpointer user_data, GCompareFunc sort_func)
Account Reconciliation information getters/setters
gboolean xaccAccountGetReconcileLastDate (const Account *account, time64 *last_date)
void xaccAccountSetReconcileLastDate (Account *account, time64 last_date)
gboolean xaccAccountGetReconcileLastInterval (const Account *account, int *months, int *days)
void xaccAccountSetReconcileLastInterval (Account *account, int months, int days)
gboolean xaccAccountGetReconcilePostponeDate (const Account *account, time64 *postpone_date)
void xaccAccountSetReconcilePostponeDate (Account *account, time64 postpone_date)
gboolean xaccAccountGetReconcilePostponeBalance (const Account *account, gnc_numeric *balance)
void xaccAccountSetReconcilePostponeBalance (Account *account, gnc_numeric balance)
void xaccAccountClearReconcilePostpone (Account *account)
Account Placeholder flag
gboolean xaccAccountGetPlaceholder (const Account *account)
void xaccAccountSetPlaceholder (Account *account, gboolean val)
GNCPlaceholderType xaccAccountGetDescendantPlaceholder (const Account *account)
Account Hidden flag
gboolean xaccAccountGetHidden (const Account *acc)
void xaccAccountSetHidden (Account *acc, gboolean val)
gboolean xaccAccountIsHidden (const Account *acc)
Account Tax related getters/setters
gboolean xaccAccountGetTaxRelated (const Account *account)
void xaccAccountSetTaxRelated (Account *account, gboolean tax_related)
const char * xaccAccountGetTaxUSCode (const Account *account)
void xaccAccountSetTaxUSCode (Account *account, const char *code)
const char * xaccAccountGetTaxUSPayerNameSource (const Account *account)
void xaccAccountSetTaxUSPayerNameSource (Account *account, const char *source)
gint64 xaccAccountGetTaxUSCopyNumber (const Account *account)
void xaccAccountSetTaxUSCopyNumber (Account *account, gint64 copy_number)
Account marking
void xaccAccountSetMark (Account *account, short mark)
void xaccClearMark (Account *account, short val)
void xaccClearMarkDown (Account *account, short val)
Staged Traversal

The following functions provide support for "staged traversals" over all of the transactions in an account or group. The idea is to be able to perform a sequence of traversals ("stages"), and perform an operation on each transaction exactly once for that stage.

Only transactions whose current "stage" is less than the stage of the current traversal will be affected, and they will be "brought up" to the current stage when they are processed.

For example, you could perform a stage 1 traversal of all the transactions in an account, and then perform a stage 1 traversal of the transactions in a second account. Presuming the traversal of the first account didn't abort prematurely, any transactions shared by both accounts would be ignored during the traversal of the second account since they had been processed while traversing the first account.

However, if you had traversed the second account using a stage of 2, then all the transactions in the second account would have been processed.

Traversal can be aborted by having the callback function return a non-zero value. The traversal is aborted immediately, and the non-zero value is returned. Note that an aborted traversal can be restarted; no information is lost due to an abort.

The initial impetus for this particular approach came from generalizing a mark/sweep practice that was already being used in FileIO.c.

Note that currently, there is a hard limit of 256 stages, which can be changed by enlarging "marker" in the transaction struct.

void gnc_account_tree_begin_staged_transaction_traversals (Account *acc)
void xaccSplitsBeginStagedTransactionTraversals (SplitList *splits)
void xaccAccountBeginStagedTransactionTraversals (const Account *account)
gboolean xaccTransactionTraverse (Transaction *trans, int stage)
int xaccAccountStagedTransactionTraversal (const Account *a, unsigned int stage, TransactionCallback thunk, void *data)
int gnc_account_tree_staged_transaction_traversal (const Account *account, unsigned int stage, TransactionCallback thunk, void *data)
int xaccAccountTreeForEachTransaction (Account *acc, TransactionCallback proc, void *data)
Deprecated Routines.
void DxaccAccountSetCurrency (Account *account, gnc_commodity *currency)
gnc_commodity * DxaccAccountGetCurrency (const Account *account)
void dxaccAccountSetQuoteTZ (Account *account, const char *tz)
const char * dxaccAccountGetQuoteTZ (const Account *account)

Account lookup and GncGUID routines

#define xaccAccountGetGUID(X)   qof_entity_get_guid(QOF_INSTANCE(X))
#define xaccAccountReturnGUID(X)   (X ? *(qof_entity_get_guid(QOF_INSTANCE(X))) : *(guid_null()))
#define xaccAccountLookupDirect(g, b)   xaccAccountLookup(&(g),b)
const gchar * gnc_get_account_separator_string (void)
gunichar gnc_get_account_separator (void)
void gnc_set_account_separator (const gchar *separator)
Accountgnc_book_get_root_account (QofBook *book)
void gnc_book_set_root_account (QofBook *book, Account *root)
AccountxaccAccountLookup (const GncGUID *guid, QofBook *book)

Account split/transaction list management

#define xaccAccountInsertSplit(acc, s)   xaccSplitSetAccount((s), (acc))
SplitListxaccAccountGetSplitList (const Account *account)
gint64 xaccAccountCountSplits (const Account *acc, gboolean include_children)
void xaccAccountMoveAllSplits (Account *accfrom, Account *accto)
gint xaccAccountForEachTransaction (const Account *account, TransactionCallback proc, void *data)
Transaction * xaccAccountFindTransByDesc (const Account *account, const char *description)
Split * xaccAccountFindSplitByDesc (const Account *account, const char *description)

Detailed Description

Account handling public routines.

Copyright (C) 1997 Robin D. Clark
Copyright (C) 1997-2003 Linas Vepstas

Definition in file Account.h.