Account
[GnuCash Engine: Core, Non-GUI Accounting Functions]

Detailed Description

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


Files

file  Account.h
 Account handling public routines.

Data Structures

struct  AccountClass

Account Constructors, Edit/Commit, Comparison

Account * xaccMallocAccount (QofBook *book)
Account * gnc_account_create_root (QofBook *book)
Account * xaccCloneAccount (const Account *from, QofBook *book)
Account * xaccCloneAccountSimple (const Account *from, 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 lookup and GUID routines

const gchar * gnc_get_account_separator_string (void)
gunichar gnc_get_account_separator (void)
void gnc_set_account_separator (const gchar *separator)
Account * gnc_book_get_root_account (QofBook *book)
void gnc_book_set_root_account (QofBook *book, Account *root)
Account * xaccAccountLookup (const GUID *guid, QofBook *book)
#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)

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 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_find_split (Account *acc, Split *s)
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 * xaccAccountGetNotes (const Account *account)
const char * xaccAccountGetLastNum (const Account *account)
GNCPolicy * gnc_account_get_policy (Account *account)
gnc_numeric gnc_account_get_start_balance (Account *acc)
gnc_numeric gnc_account_get_start_cleared_balance (Account *acc)
gnc_numeric gnc_account_get_start_reconciled_balance (Account *acc)
gboolean gnc_account_get_balance_dirty (Account *acc)
gboolean gnc_account_get_sort_dirty (Account *acc)
void xaccAccountRecomputeBalance (Account *)
void xaccAccountSortSplits (Account *acc, gboolean force)
char * xaccAccountGetFullName (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)
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)
#define DxaccAccountSetSecurity   xaccAccountSetCommodity
#define DxaccAccountGetSecurity   xaccAccountGetCommodity
#define xaccAccountSetCommoditySCUandFlag   xaccAccountSetCommoditySCU

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, time_t 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, time_t 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, time_t date, gnc_commodity *report_commodity, gboolean include_children)
gnc_numeric xaccAccountGetBalanceChangeForPeriod (Account *acc, time_t date1, time_t 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. To make the management of sets of accounts easier, an account does not directly point at its children, but rather at an 'Account Group' that stores the children. At the top of the tree heirarchy lies a single root node, the root account group.

The account tree heirarchy 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)
Account * gnc_account_get_parent (const Account *account)
Account * gnc_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)
Account * gnc_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)

ForEach

void gnc_account_foreach_child (const Account *account, AccountCb func, gpointer user_data)
gpointer gnc_account_foreach_child_until (const Account *account, AccountCb2 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_copy_children (Account *dest, Account *src)
void gnc_account_merge_children (Account *parent)

Defines

#define GNC_TYPE_ACCOUNT   (gnc_account_get_type ())
#define GNC_ACCOUNT(o)   (G_TYPE_CHECK_INSTANCE_CAST ((o), GNC_TYPE_ACCOUNT, Account))
#define GNC_ACCOUNT_CLASS(k)   (G_TYPE_CHECK_CLASS_CAST((k), GNC_TYPE_ACCOUNT, AccountClass))
#define GNC_IS_ACCOUNT(o)   (G_TYPE_CHECK_INSTANCE_TYPE ((o), GNC_TYPE_ACCOUNT))
#define GNC_IS_ACCOUNT_CLASS(k)   (G_TYPE_CHECK_CLASS_TYPE ((k), GNC_TYPE_ACCOUNT))
#define GNC_ACCOUNT_GET_CLASS(o)   (G_TYPE_INSTANCE_GET_CLASS ((o), GNC_TYPE_ACCOUNT, AccountClass))
#define xaccAccountGetSlots(X)   qof_instance_get_slots(QOF_INSTANCE(X))

Typedefs

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, time_t date)
typedef void(*) AccountCb (Account *a, gpointer data)
typedef gpointer(*) AccountCb2 (Account *a, gpointer data)

Enumerations

enum  GNCAccountType {
  ACCT_TYPE_INVALID = -1, ACCT_TYPE_NONE = -1, ACCT_TYPE_BANK = 0, ACCT_TYPE_CASH = 1,
  ACCT_TYPE_CREDIT = 3, ACCT_TYPE_ASSET = 2, ACCT_TYPE_LIABILITY = 4, ACCT_TYPE_STOCK = 5,
  ACCT_TYPE_MUTUAL = 6, ACCT_TYPE_CURRENCY = 7, ACCT_TYPE_INCOME = 8, ACCT_TYPE_EXPENSE = 9,
  ACCT_TYPE_EQUITY = 10, ACCT_TYPE_RECEIVABLE = 11, ACCT_TYPE_PAYABLE = 12, ACCT_TYPE_ROOT = 13,
  NUM_ACCOUNT_TYPES = 14, ACCT_TYPE_CHECKING = 14, ACCT_TYPE_SAVINGS = 15, ACCT_TYPE_MONEYMRKT = 16,
  ACCT_TYPE_CREDITLINE = 17
}

Functions

GType gnc_account_get_type (void)
void xaccAccountSetReconcileChildrenStatus (Account *account, gboolean status)
gboolean xaccAccountGetReconcileChildrenStatus (const Account *account)
gboolean xaccAccountHasAncestor (const Account *acc, const Account *ancestor)

Define Documentation

#define DxaccAccountGetSecurity   xaccAccountGetCommodity

Deprecated:
do not use

Definition at line 481 of file Account.h.

#define DxaccAccountSetSecurity   xaccAccountSetCommodity

Deprecated:
do not use

Definition at line 475 of file Account.h.

#define xaccAccountGetGUID ( X   )     qof_entity_get_guid(QOF_INSTANCE(X))

Deprecated:

Definition at line 235 of file Account.h.

#define xaccAccountSetCommoditySCUandFlag   xaccAccountSetCommoditySCU

Deprecated:
-- do not use for future development

Definition at line 500 of file Account.h.

Enumeration Type Documentation

enum GNCAccountType

The account types are used to determine how the transaction data in the account is displayed. These values can be safely changed from one release to the next. Note that if values are added, the file IO translation routines need to be updated. Note also that GUI code depends on these numbers.

Note:
***IMPORTANT***: If you do change the enumeration names (not the numbers), you need to update xaccAccountTypeEnumAsString --- used for text file exports
Enumerator:
ACCT_TYPE_INVALID  Not a type
ACCT_TYPE_NONE  Not a type
ACCT_TYPE_BANK  The bank account type denotes a savings or checking account held at a bank. Often * interest * bearing.
ACCT_TYPE_CASH  The cash account type is used to denote a shoe-box or pillowcase stuffed with * cash.
ACCT_TYPE_CREDIT  The Credit card account is used to denote credit (e.g. amex) and debit (e.g. visa, mastercard) * card accounts
ACCT_TYPE_ASSET  asset (and liability) accounts indicate generic, generalized accounts that are none of the * above.
ACCT_TYPE_LIABILITY  liability (and asset) accounts indicate generic, generalized accounts that are none of the * above.
ACCT_TYPE_STOCK  Stock accounts will typically be shown in registers which show three columns: price, number of * shares, and value.
ACCT_TYPE_MUTUAL  Mutual Fund accounts will typically be shown in registers which show three columns: price, * number of shares, and value.
ACCT_TYPE_CURRENCY  The currency account type indicates that the account is a currency trading account. In many * ways, a currency trading account is like a stock * trading account. It is shown in the register with * three columns: price, number of shares, and * value. Note: Since version 1.7.0, this account is * no longer needed to exchange currencies between * accounts, so this type is DEPRECATED.
ACCT_TYPE_INCOME  Income accounts are used to denote income
ACCT_TYPE_EXPENSE  Expense accounts are used to denote expenses.
ACCT_TYPE_EQUITY  Equity account is used to balance the balance sheet.
ACCT_TYPE_RECEIVABLE  A/R account type
ACCT_TYPE_PAYABLE  A/P account type
ACCT_TYPE_ROOT  The hidden root account of an account tree.
NUM_ACCOUNT_TYPES  stop here; the following types just aren't ready for prime time
ACCT_TYPE_CHECKING  bank account type -- don't use this for now, see NUM_ACCOUNT_TYPES
ACCT_TYPE_SAVINGS  bank account type -- don't use this for now, see NUM_ACCOUNT_TYPES
ACCT_TYPE_MONEYMRKT  bank account type -- don't use this for now, see NUM_ACCOUNT_TYPES
ACCT_TYPE_CREDITLINE  line of credit -- don't use this for now, see NUM_ACCOUNT_TYPES

Definition at line 91 of file Account.h.

00092 {
00093   ACCT_TYPE_INVALID = -1, 
00094   ACCT_TYPE_NONE = -1,
00096   ACCT_TYPE_BANK = 0,   
00099   ACCT_TYPE_CASH = 1,   
00102   ACCT_TYPE_CREDIT = 3, 
00105   ACCT_TYPE_ASSET = 2,  
00108   ACCT_TYPE_LIABILITY = 4,
00111   ACCT_TYPE_STOCK = 5,  
00114   ACCT_TYPE_MUTUAL= 6,  
00118   ACCT_TYPE_CURRENCY = 7,
00129   ACCT_TYPE_INCOME = 8, 
00132   ACCT_TYPE_EXPENSE = 9,
00135   ACCT_TYPE_EQUITY = 10,
00138   ACCT_TYPE_RECEIVABLE = 11,
00140   ACCT_TYPE_PAYABLE = 12,  
00142   ACCT_TYPE_ROOT = 13, 
00144   NUM_ACCOUNT_TYPES = 14,  
00147   /* bank account types */
00148   ACCT_TYPE_CHECKING = 14, 
00150   ACCT_TYPE_SAVINGS = 15, 
00152   ACCT_TYPE_MONEYMRKT = 16, 
00154   ACCT_TYPE_CREDITLINE = 17, 
00156 } GNCAccountType;

Function Documentation

const char* dxaccAccountGetPriceSrc ( const Account *  account  ) 

Get a string that identifies the Finance::Quote backend that should be used to retrieve online prices. See price-quotes.scm for more information.

Deprecated:
Price quote information is now stored on the commodity, not the account.

Definition at line 4013 of file Account.c.

04014 {
04015   if(!acc) return NULL;
04016 
04017   if (xaccAccountIsPriced(acc)) {
04018       KvpValue *value = kvp_frame_get_slot(acc->inst.kvp_data, 
04019                                            "old-price-source");
04020       if (value) return (kvp_value_get_string(value));
04021   }
04022   return NULL;
04023 }

void dxaccAccountSetPriceSrc ( Account *  account,
const char *  src 
)

Set a string that identifies the Finance::Quote backend that should be used to retrieve online prices. See price-quotes.scm for more information

Deprecated:
Price quote information is now stored on the commodity, not the account.

Definition at line 3993 of file Account.c.

03994 {
03995   if (!acc) return;
03996 
03997   xaccAccountBeginEdit(acc);
03998   if (xaccAccountIsPriced(acc)) {
03999       kvp_frame_set_slot_nc(acc->inst.kvp_data,
04000                             "old-price-source",
04001                             src ? kvp_value_new_string(src) : NULL);
04002       mark_account (acc);
04003   }
04004   
04005   qof_instance_set_dirty(&acc->inst);
04006   xaccAccountCommitEdit(acc);
04007 }

void gnc_account_append_child ( Account *  new_parent,
Account *  child 
)

This function will remove from the child account any pre-existing parent relationship, and will then add the account as a child of the new parent. The exception to this is when the old and new parent accounts are the same, in which case this function does nothing.

If the child account belongs to a different book than the specified new parent account, the child will be removed from the other book (and thus, the other book's entity tables, generating a destroy event), and will be added to the new book (generating a create event).

Parameters:
new_parent The new parent account to which the child should be attached.
child The account to attach.

Definition at line 2192 of file Account.c.

02193 {
02194   AccountPrivate *ppriv, *cpriv;
02195   Account *old_parent;
02196   QofCollection *col;
02197 
02198   /* errors */
02199   g_assert(GNC_IS_ACCOUNT(new_parent));
02200   g_assert(GNC_IS_ACCOUNT(child));
02201 
02202   /* optimizations */
02203   ppriv = GET_PRIVATE(new_parent);
02204   cpriv = GET_PRIVATE(child);
02205   old_parent = cpriv->parent;
02206   if (old_parent == new_parent)
02207     return;
02208 
02209   //  xaccAccountBeginEdit(new_parent);
02210   xaccAccountBeginEdit(child);
02211   if (old_parent) {
02212     gnc_account_remove_child(old_parent, child);
02213 
02214     if (!qof_instance_books_equal(old_parent, new_parent)) {
02215       /* hack alert -- this implementation is not exactly correct.
02216        * If the entity tables are not identical, then the 'from' book 
02217        * may have a different backend than the 'to' book.  This means
02218        * that we should get the 'from' backend to destroy this account,
02219        * and the 'to' backend to save it.  Right now, this is broken.
02220        *  
02221        * A 'correct' implementation similar to this is in Period.c
02222        * except its for transactions ...
02223        *
02224        * Note also, we need to reparent the children to the new book as well.
02225        */
02226       PWARN ("reparenting accounts across books is not correctly supported\n");
02227 
02228       qof_event_gen (&child->inst, QOF_EVENT_DESTROY, NULL);
02229       col = qof_book_get_collection (qof_instance_get_book(new_parent),
02230                                      GNC_ID_ACCOUNT);
02231       qof_collection_insert_entity (col, &child->inst);
02232       qof_event_gen (&child->inst, QOF_EVENT_CREATE, NULL);
02233     }
02234   }
02235   cpriv->parent = new_parent;
02236   ppriv->children = g_list_append(ppriv->children, child);
02237   qof_instance_set_dirty(&new_parent->inst);
02238   qof_instance_set_dirty(&child->inst);
02239 
02240   /* Send events data. Warning: The call to commit_edit is also gpoing
02241    * to send a MODIFY event. If the gtktreemodelfilter code gets the
02242    * MODIFY before it gets the ADD, it gets very confused and thinks
02243    * that two nodes have been added. */
02244   qof_event_gen (&child->inst, QOF_EVENT_ADD, NULL);
02245   // qof_event_gen (&new_parent->inst, QOF_EVENT_MODIFY, NULL);
02246 
02247   xaccAccountCommitEdit (child);
02248   //  xaccAccountCommitEdit(new_parent);
02249 }

gint gnc_account_child_index ( const Account *  parent,
const Account *  child 
)

Return the index of the specified child within the list of the parent's children. The first child index is 0. This function returns -1 if the parent account is NULL of if the specified child does not belong to the parent account.

Parameters:
parent The parent account to check.
child The child account to find.
Returns:
The index of the child account within the specified parent, or -1.

Definition at line 2347 of file Account.c.

02348 {
02349     g_return_val_if_fail(GNC_IS_ACCOUNT(parent), -1);
02350     g_return_val_if_fail(GNC_IS_ACCOUNT(child), -1);
02351     return g_list_index(GET_PRIVATE(parent)->children, child);
02352 }

void gnc_account_copy_children ( Account *  dest,
Account *  src 
)

The gnc_account_copy_children() subroutine will copy all child accounts from the "src" account to the "dest" account, preserving the account heirarchy. It will also take care that the moved accounts will have the "dest" account's book parent as well. This routine will *NOT* copy any splits/transactions. It will copy the KVP trees in each account.

Definition at line 4181 of file Account.c.

04182 {
04183    AccountPrivate *to_priv, *from_priv;
04184    GList *node;
04185    QofBook *to_book;
04186 
04187    /* errors */
04188    g_return_if_fail(GNC_IS_ACCOUNT(to));
04189    g_return_if_fail(GNC_IS_ACCOUNT(from));
04190 
04191    /* optimizations */
04192    to_priv = GET_PRIVATE(to);
04193    from_priv = GET_PRIVATE(from);
04194    if (!from_priv->children)
04195        return;
04196 
04197    to_book = gnc_account_get_book(to);
04198    if (!to_book) return;
04199 
04200    ENTER (" ");
04201    xaccAccountBeginEdit(to);
04202    xaccAccountBeginEdit(from);
04203    for (node = from_priv->children; node; node=node->next)
04204    {
04205       Account *to_acc, *from_acc = node->data;
04206 
04207       /* This will copy the basic data and the KVP.  It will
04208        * not copy any splits/transactions. It will gemini. */
04209       to_acc = xaccCloneAccount (from_acc, to_book);
04210 
04211       xaccAccountBeginEdit (to_acc);
04212       to_priv->children = g_list_append(to_priv->children, to_acc);
04213 
04214       GET_PRIVATE(to_acc)->parent = to;
04215       qof_instance_set_dirty(&to_acc->inst);
04216 
04217       /* Copy child accounts too. */
04218       if (GET_PRIVATE(from_acc)->children)
04219       {
04220         gnc_account_copy_children(to_acc, from_acc);
04221       }
04222       xaccAccountCommitEdit (to_acc);
04223       qof_event_gen (&to_acc->inst, QOF_EVENT_CREATE, NULL);
04224       /* DRH - Should this send ADD/REMOVE events */
04225    }
04226    xaccAccountCommitEdit(from);
04227    xaccAccountCommitEdit(to);
04228    LEAVE (" ");
04229 }

Account* gnc_account_create_root ( QofBook *  book  ) 

Create a new root level account.

Definition at line 827 of file Account.c.

00828 {
00829   Account *root;
00830   AccountPrivate *rpriv;
00831 
00832   root = xaccMallocAccount(book);
00833   rpriv = GET_PRIVATE(root);
00834   xaccAccountBeginEdit(root);
00835   rpriv->type = ACCT_TYPE_ROOT;
00836   CACHE_REPLACE(rpriv->accountName, "Root Account");
00837   xaccAccountCommitEdit(root);
00838   gnc_book_set_root_account(book, root);
00839   return root;
00840 }

gboolean gnc_account_find_split ( Account *  acc,
Split *  s 
)

Find the given split in an account.

Parameters:
acc The account whose splits are to be searched.
s The split to be found.
Returns:
TRUE is the split is found in the accounts list of splits. FALSE otherwise.

Definition at line 1443 of file Account.c.

01444 {
01445     AccountPrivate *priv;
01446     GList *node;
01447 
01448     g_return_val_if_fail(GNC_IS_ACCOUNT(acc), FALSE);
01449     g_return_val_if_fail(GNC_IS_SPLIT(s), FALSE);
01450 
01451     priv = GET_PRIVATE(acc);
01452     node = g_list_find(priv->splits, s);
01453     return node ? TRUE : FALSE;
01454 }

void gnc_account_foreach_child ( const Account *  account,
AccountCb  func,
gpointer  user_data 
)

This method will traverse the immediate children of this accounts, calling 'func' on each account. This function traverses all children nodes. To traverse only a subset of the child nodes use the gnc_account_foreach_child_until() function.

Parameters:
account A pointer to the account on whose children the function should be called.
func A function taking two arguments, an Account and a gpointer.
user_data This data will be passed to each call of func.

Definition at line 2562 of file Account.c.

02565 {
02566     const AccountPrivate *priv;
02567     GList *node;
02568 
02569     g_return_if_fail(GNC_IS_ACCOUNT(acc));
02570     g_return_if_fail(thunk);
02571 
02572     priv = GET_PRIVATE(acc);
02573     for (node = priv->children; node; node = node->next) {
02574         thunk (node->data, user_data);
02575     }
02576 }

gpointer gnc_account_foreach_child_until ( const Account *  account,
AccountCb2  func,
gpointer  user_data 
)

This method will traverse the immediate children of this accounts, calling 'func' on each account. Traversal will stop when func returns a non-null value, and the routine will return with that value. Therefore, this function will return null iff func returns null for every account. For a simpler function that always traverses all children nodes, use the gnc_account_foreach_child() function.

Parameters:
account A pointer to the account on whose children the function should be called.
func A function taking two arguments, an Account and a gpointer.
user_data This data will be passed to each call of func.

Definition at line 2579 of file Account.c.

02582 {
02583     const AccountPrivate *priv;
02584     GList *node;
02585     gpointer result;
02586 
02587     g_return_val_if_fail(GNC_IS_ACCOUNT(acc), NULL);
02588     g_return_val_if_fail(thunk, NULL);
02589 
02590     priv = GET_PRIVATE(acc);
02591     for (node = priv->children; node; node = node->next) {
02592         result = thunk (node->data, user_data);
02593         if (result)
02594             return(result);
02595     }
02596 
02597     return NULL;
02598 }

void gnc_account_foreach_descendant ( const Account *  account,
AccountCb  func,
gpointer  user_data 
)

This method will traverse all children of this accounts and their descendants, calling 'func' on each account. This function traverses all descendant nodes. To traverse only a subset of the descendant nodes use the gnc_account_foreach_descendant_until() function.

Parameters:
account A pointer to the account on whose descendants the function should be called.
func A function taking two arguments, an Account and a gpointer.
user_data This data will be passed to each call of func.

Definition at line 2601 of file Account.c.

02604 {
02605     const AccountPrivate *priv;
02606     GList *node;
02607     Account *child;
02608 
02609     g_return_if_fail(GNC_IS_ACCOUNT(acc));
02610     g_return_if_fail(thunk);
02611 
02612     priv = GET_PRIVATE(acc);
02613     for (node = priv->children; node; node = node->next) {
02614         child = node->data;
02615         thunk(child, user_data);
02616         gnc_account_foreach_descendant(child, thunk, user_data);
02617     }
02618 }

gpointer gnc_account_foreach_descendant_until ( const Account *  account,
AccountCb2  func,
gpointer  user_data 
)

This method will traverse all children of this accounts and their descendants, calling 'func' on each account. Traversal will stop when func returns a non-null value, and the routine will return with that value. Therefore, this function will return null iff func returns null for every account. For a simpler function that always traverses all children nodes, use the gnc_account_foreach_descendant() function.

Parameters:
account A pointer to the account on whose descendants the function should be called.
func A function taking two arguments, an Account and a gpointer.
user_data This data will be passed to each call of func.

Definition at line 2621 of file Account.c.

02624 {
02625     const AccountPrivate *priv;
02626     GList *node;
02627     Account *child;
02628     gpointer result;
02629 
02630     g_return_val_if_fail(GNC_IS_ACCOUNT(acc), NULL);
02631     g_return_val_if_fail(thunk, NULL);
02632 
02633     priv = GET_PRIVATE(acc);
02634     for (node = priv->children; node; node = node->next) {
02635         child = node->data;
02636         result = thunk(child, user_data);
02637         if (result)
02638             return(result);
02639 
02640         result = gnc_account_foreach_descendant_until(child, thunk, user_data);
02641         if (result)
02642             return(result);
02643     }
02644 
02645     return NULL;
02646 }

gboolean gnc_account_get_balance_dirty ( Account *  acc  ) 

Get an indication of whether the account believes that the running balances may be incorrect and need to be recomputed.

Parameters:
acc Retrieve the flag on this account.
Returns:
TRUE if the running account balances need to be recomputed. FALSE if they are correct.

Definition at line 1419 of file Account.c.

01420 {
01421     g_return_val_if_fail(GNC_IS_ACCOUNT(acc), FALSE);
01422     return GET_PRIVATE(acc)->balance_dirty;
01423 }

GList* gnc_account_get_children ( const Account *  account  ) 

This routine returns a GList of all children of the specified account. This function only returns the immediate children of the specified account. For a list of all descendant accounts, use the gnc_account_get_descendants() function.

Parameters:
account The account whose children should be returned.
Returns:
A GList of account pointers, or NULL if there are no children. It is the callers responsibility to free any returned list with the g_list_free() function.

Definition at line 2318 of file Account.c.

02319 {
02320     g_return_val_if_fail(GNC_IS_ACCOUNT(account), NULL);
02321     return g_list_copy(GET_PRIVATE(account)->children);
02322 }

gint gnc_account_get_current_depth ( const Account *  account  ) 

Return the number of levels of this account below the root account.

Parameters:
account The account to query.
Returns:
The number of levels below the root.

Definition at line 2378 of file Account.c.

02379 {
02380     AccountPrivate *priv;
02381     int depth = 0;
02382 
02383     g_return_val_if_fail(GNC_IS_ACCOUNT(account), 0);
02384 
02385     priv = GET_PRIVATE(account);
02386     while (priv->parent && (priv->type != ACCT_TYPE_ROOT)) {
02387         account = priv->parent;
02388         priv = GET_PRIVATE(account);
02389         depth++;
02390     }
02391 
02392     return depth;
02393 }

GList* gnc_account_get_descendants ( const Account *  account  ) 

This routine returns a flat list of all of the accounts that are descendants of the specified account. This includes not only the the children, but the children of the children, etc. For a list of only the immediate child accounts, use the gnc_account_get_children() function. Within each set of child accounts, the accounts returned by this function are unordered. For a list of descendants where each set of children is sorted via the standard account sort function, use the gnc_account_get_descendants_sorted() function.

Parameters:
account The account whose descendants should be returned.
Returns:
A GList of account pointers, or NULL if there are no descendants. It is the callers responsibility to free any returned list with the g_list_free() function.

Definition at line 2416 of file Account.c.

02417 {
02418   AccountPrivate *priv;
02419   GList *child, *descendants;
02420 
02421   g_return_val_if_fail(GNC_IS_ACCOUNT(account), NULL);
02422 
02423   priv = GET_PRIVATE(account);
02424   if (!priv->children)
02425     return NULL;
02426 
02427   descendants = NULL;
02428   for (child = priv->children; child; child = g_list_next(child)) {
02429     descendants = g_list_append(descendants, child->data);
02430     descendants = g_list_concat(descendants,
02431                                 gnc_account_get_descendants(child->data));
02432   }
02433   return descendants;
02434 }

GList* gnc_account_get_descendants_sorted ( const Account *  account  ) 

This function returns a GList containing all the descendants of the specified account, sorted at each level. This includes not only the the children, but the children of the children, etc. Within each set of child accounts, the accounts returned by this function are ordered via the standard account sort function. For a list of descendants where each set of children is unordered, use the gnc_account_get_descendants() function.

Note: Use this function where the results are intended for display to the user. If the results are internal to GnuCash or will be resorted at som later point in time you should use the gnc_account_get_descendants() function.

Parameters:
account The account whose descendants should be returned.
Returns:
A GList of account pointers, or NULL if there are no descendants. It is the callers responsibility to free any returned list with the g_list_free() function.

Definition at line 2437 of file Account.c.

02438 {
02439   AccountPrivate *priv;
02440   GList *child, *children, *descendants;
02441 
02442   /* errors */
02443   g_return_val_if_fail(GNC_IS_ACCOUNT(account), NULL);
02444 
02445   /* optimizations */
02446   priv = GET_PRIVATE(account);
02