/
Account.h
1585 lines (1378 loc) · 63.1 KB
/
Account.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/********************************************************************\
* This program is free software; you can redistribute it and/or *
* modify it under the terms of the GNU General Public License as *
* published by the Free Software Foundation; either version 2 of *
* the License, or (at your option) any later version. *
* *
* This program is distributed in the hope that it will be useful, *
* but WITHOUT ANY WARRANTY; without even the implied warranty of *
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
* GNU General Public License for more details. *
* *
* You should have received a copy of the GNU General Public License*
* along with this program; if not, contact: *
* *
* Free Software Foundation Voice: +1-617-542-5942 *
* 51 Franklin Street, Fifth Floor Fax: +1-617-542-2652 *
* Boston, MA 02110-1301, USA gnu@gnu.org *
* *
\********************************************************************/
/** @addtogroup Engine
@{ */
/** @addtogroup Account
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 tradeable: 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.
@{ */
/** @file Account.h
@brief Account handling public routines
@author Copyright (C) 1997 Robin D. Clark
@author Copyright (C) 1997-2003 Linas Vepstas <linas@linas.org>
*/
#ifndef XACC_ACCOUNT_H
#define XACC_ACCOUNT_H
#include "qof.h"
#include "gnc-engine.h"
#include "policy.h"
#ifdef __cplusplus
extern "C" {
#endif
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);
typedef struct
{
QofInstanceClass parent_class;
} AccountClass;
typedef struct
{
Account *acc;
QofBook *book;
} GncImportMatchMap;
/* --- type macros --- */
#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))
/** Returns the GType type system description of the Account class.
*
* This must not be confused with the \ref GNCAccountType as returned
* by xaccAccountGetType(). */
GType gnc_account_get_type(void);
/** 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 */
typedef enum
{
ACCT_TYPE_INVALID = -1, /**< Not a type */
ACCT_TYPE_NONE = -1,/**< Not a type */
ACCT_TYPE_BANK = 0, /**< The bank account type denotes a savings
* or checking account held at a bank.
* Often interest bearing. */
ACCT_TYPE_CASH = 1, /**< The cash account type is used to denote a
* shoe-box or pillowcase stuffed with *
* cash. */
ACCT_TYPE_CREDIT = 3, /**< The Credit card account is used to denote
* credit (e.g. amex) and debit (e.g. visa,
* mastercard) card accounts */
ACCT_TYPE_ASSET = 2, /**< asset (and liability) accounts indicate
* generic, generalized accounts that are
* none of the above. */
ACCT_TYPE_LIABILITY = 4,/**< liability (and asset) accounts indicate
* generic, generalized accounts that are
* none of the above. */
ACCT_TYPE_STOCK = 5, /**< Stock accounts will typically be shown in
* registers which show three columns:
* price, number of shares, and value. */
ACCT_TYPE_MUTUAL = 6, /**< Mutual Fund accounts will typically be
* shown in registers which show three
* columns: price, number of shares, and
* value. */
ACCT_TYPE_CURRENCY = 7,/**< 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 = 8, /**< Income accounts are used to denote
* income */
ACCT_TYPE_EXPENSE = 9,/**< Expense accounts are used to denote
* expenses. */
ACCT_TYPE_EQUITY = 10,/**< Equity account is used to balance the
* balance sheet. */
ACCT_TYPE_RECEIVABLE = 11,/**< A/R account type */
ACCT_TYPE_PAYABLE = 12, /**< A/P account type */
ACCT_TYPE_ROOT = 13, /**< The hidden root account of an account tree. */
ACCT_TYPE_TRADING = 14, /**< Account used to record multiple commodity transactions.
* This is not the same as ACCT_TYPE_CURRENCY above.
* Multiple commodity transactions have splits in these
* accounts to make the transaction balance in each
* commodity as well as in total value. */
NUM_ACCOUNT_TYPES = 15, /**< stop here; the following types
* just aren't ready for prime time */
/* bank account types */
ACCT_TYPE_CHECKING = 15, /**< bank account type -- don't use this
* for now, see NUM_ACCOUNT_TYPES */
ACCT_TYPE_SAVINGS = 16, /**< bank account type -- don't use this for
* now, see NUM_ACCOUNT_TYPES */
ACCT_TYPE_MONEYMRKT = 17, /**< bank account type -- don't use this
* for now, see NUM_ACCOUNT_TYPES */
ACCT_TYPE_CREDITLINE = 18, /**< line of credit -- don't use this for
* now, see NUM_ACCOUNT_TYPES */
ACCT_TYPE_LAST
} GNCAccountType;
/** @name Account Constructors, Edit/Commit, Comparison
@{ */
/** Constructor */
Account * xaccMallocAccount (QofBook *book);
/** Create a new root level account. */
Account * gnc_account_create_root (QofBook *book);
/** The xaccCloneAccount() routine makes a simple copy of the
* indicated account, placing it in the indicated book. It copies
* the account type, name, description, and the kvp values;
* it does not copy splits/transactions. The book should have
* a commodity table in it that has commodities with the same
* unique name as the ones being copied in the account (the
* commodities in the clone will be those from the book).
*/
Account * xaccCloneAccount (const Account *source, QofBook *book);
/** The xaccAccountBeginEdit() subroutine is the first phase of
* a two-phase-commit wrapper for account updates. */
void xaccAccountBeginEdit (Account *account);
/** ThexaccAccountCommitEdit() subroutine is the second phase of
* a two-phase-commit wrapper for account updates. */
void xaccAccountCommitEdit (Account *account);
/** The xaccAccountDestroy() routine can be used to get rid of an
* account. The account should have been opened for editing
* (by calling xaccAccountBeginEdit()) before calling this routine.*/
void xaccAccountDestroy (Account *account);
/** Compare two accounts for equality - this is a deep compare. */
gboolean xaccAccountEqual(const Account *a, const Account* b,
gboolean check_guids);
/** The xaccAccountOrder() subroutine defines a sorting order on
* accounts. It takes pointers to two accounts, and returns an int < 0 if
* the first account is "less than" the second, returns an int > 0 if the
* first is "greater than" the second, and 0 if they are equal. To
* determine the sort order, first the account codes are compared,
* and if these are equal, then account types, then account
* names. If still equal, it compares GUID to ensure that there
* aren't any ties.
*/
int xaccAccountOrder (const Account *account_1, const Account *account_2);
/** @} */
/* ------------------ */
/** @name Account lookup and GncGUID routines
@{ */
/** Returns the account separation character chosen by the user.
*
* @return The character to use.
*/
const gchar *gnc_get_account_separator_string (void);
gunichar gnc_get_account_separator (void);
void gnc_set_account_separator (const gchar *separator);
/*@ dependent @*/
Account *gnc_book_get_root_account(QofBook *book);
void gnc_book_set_root_account(QofBook *book, Account *root);
/** @deprecated */
#define xaccAccountGetGUID(X) qof_entity_get_guid(QOF_INSTANCE(X))
#define xaccAccountReturnGUID(X) (X ? *(qof_entity_get_guid(QOF_INSTANCE(X))) : *(guid_null()))
/** The xaccAccountLookup() subroutine will return the
* account associated with the given id, or NULL
* if there is no such account. */
/*@ dependent @*/ Account * xaccAccountLookup (const GncGUID *guid, QofBook *book);
#define xaccAccountLookupDirect(g,b) xaccAccountLookup(&(g),b)
/** @} */
/** Composes a translatable error message showing which account
* names clash with the current account separator. Can be called
* after gnc_account_list_name_violations to have a consistent
* error message in different parts of GnuCash
*
* @param separator The separator character that was verified against
* @param invalid_account_names A GList of invalid account names.
*
* @return An error message that can be displayed to the user or logged.
* This message string should be freed with g_free when no longer
* needed.
*/
gchar *gnc_account_name_violations_errmsg (const gchar *separator, GList* invalid_account_names);
/** Runs through all the accounts and returns a list of account names
* that contain the provided separator character. This can be used to
* check if certain account names are invalid.
*
* @param book Pointer to the book with accounts to verify
* @param separator The separator character to verify against
*
* @return A GList of invalid account names. Should be freed with g_list_free
* if no longer needed.
*/
GList *gnc_account_list_name_violations (QofBook *book, const gchar *separator);
/* ------------------ */
/** @name Account general setters/getters
@{ */
QofBook *gnc_account_get_book(const Account *account);
/** Set the account's type */
void xaccAccountSetType (Account *account, GNCAccountType);
/** Set the account's name */
void xaccAccountSetName (Account *account, const char *name);
/** Set the account's accounting code */
void xaccAccountSetCode (Account *account, const char *code);
/** Set the account's description */
void xaccAccountSetDescription (Account *account, const char *desc);
/** Set the account's Color */
void xaccAccountSetColor (Account *account, const char *color);
/** Set the account's Filter */
void xaccAccountSetFilter (Account *account, const char *filter);
/** Set the account's Sort Order */
void xaccAccountSetSortOrder (Account *account, const char *sortorder);
/** Set the account's Sort Order direction */
void xaccAccountSetSortReversed (Account *account, gboolean sortreversed);
/** Set the account's notes */
void xaccAccountSetNotes (Account *account, const char *notes);
/** Set the last num field of an Account */
void xaccAccountSetLastNum (Account *account, const char *num);
/** Set the account's lot order policy */
void gnc_account_set_policy (Account *account, GNCPolicy *policy);
/** Returns the account's account type.
*
* This must not be confused with the \ref GType as returned by
* gnc_account_get_type(), which is related to glib's type system. */
GNCAccountType xaccAccountGetType (const Account *account);
/** Returns true if the account is a stock, mutual fund or currency,
* otherwise false. */
gboolean xaccAccountIsPriced(const Account *acc);
/** This function will set the starting commodity balance for this
* account. This routine is intended for use with backends that do
* not return the complete list of splits for an account, but rather
* return a partial list. In such a case, the backend will typically
* return all of the splits after some certain date, and the
* 'starting balance' will represent the summation of the splits up
* to that date. */
void gnc_account_set_start_balance (Account *acc,
const gnc_numeric start_baln);
/** This function will set the starting cleared commodity balance for
* this account. This routine is intended for use with backends that
* do not return the complete list of splits for an account, but
* rather return a partial list. In such a case, the backend will
* typically return all of the splits after some certain date, and
* the 'starting balance' will represent the summation of the splits
* up to that date. */
void gnc_account_set_start_cleared_balance (Account *acc,
const gnc_numeric start_baln);
/** This function will set the starting reconciled commodity balance
* for this account. This routine is intended for use with backends
* that do not return the complete list of splits for an account, but
* rather return a partial list. In such a case, the backend will
* typically return all of the splits after some certain date, and
* the 'starting balance' will represent the summation of the splits
* up to that date. */
void gnc_account_set_start_reconciled_balance (Account *acc,
const gnc_numeric start_baln);
/** Tell the account that the running balances may be incorrect and
* need to be recomputed.
*
* @param acc Set the flag on this account. */
void gnc_account_set_balance_dirty (Account *acc);
/** Tell the account believes that the splits may be incorrectly
* sorted and need to be resorted.
*
* @param acc Set the flag on this account. */
void gnc_account_set_sort_dirty (Account *acc);
/** Set the defer balance flag. If defer is true, the account balance
* is not automatically computed, which can save a lot of time if
* multiple operations have to be done on the same account. If
* defer is false, further operations on account will cause the
* balance to be recomputed as normal.
*
* @param acc Set the flag on this account.
*
* @param defer New value for the flag. */
void gnc_account_set_defer_bal_computation (Account *acc, gboolean defer);
/** Insert the given split from an account.
*
* @param acc The account to which the split should be added.
*
* @param s The split to be added.
*
* @result TRUE is the split is successfully added to the set of
* splits in the account. FALSE if the addition fails for any reason
* (including that the split is already in the account). */
gboolean gnc_account_insert_split (Account *acc, Split *s);
/** Remove the given split from an account.
*
* @param acc The account from which the split should be removed.
*
* @param s The split to be removed.
*
* @result TRUE is the split is successfully removed from the set of
* splits in the account. FALSE if the removal fails for any
* reason. */
gboolean gnc_account_remove_split (Account *acc, Split *s);
/** Get the account's name */
const char * xaccAccountGetName (const Account *account);
/** Get the account's accounting code */
const char * xaccAccountGetCode (const Account *account);
/** Get the account's description */
const char * xaccAccountGetDescription (const Account *account);
/** Get the account's color */
const char * xaccAccountGetColor (const Account *account);
/** Get the account's filter */
const char * xaccAccountGetFilter (const Account *account);
/** Get the account's Sort Order */
const char * xaccAccountGetSortOrder (const Account *account);
/** Get the account's Sort Order direction */
gboolean xaccAccountGetSortReversed (const Account *account);
/** Get the account's notes */
const char * xaccAccountGetNotes (const Account *account);
/** Get the last num field of an Account */
const char * xaccAccountGetLastNum (const Account *account);
/** Get the account's lot order policy */
GNCPolicy *gnc_account_get_policy (Account *account);
/** Get the account's flag for deferred balance computation */
gboolean gnc_account_get_defer_bal_computation (Account *acc);
/** The following recompute the partial balances (stored with the
* transaction) and the total balance, for this account
*/
void xaccAccountRecomputeBalance (Account *);
/** The xaccAccountSortSplits() routine will resort the account's
* splits if the sort is dirty. If 'force' is true, the account
* is sorted even if the editlevel is not zero.
*/
void xaccAccountSortSplits (Account *acc, gboolean force);
/** The gnc_account_get_full_name routine returns the fully qualified name
* of the account using the given separator char. The name must be
* g_free'd after use. The fully qualified name of an account is the
* concatenation of the names of the account and all its ancestor
* accounts starting with the topmost account and ending with the
* given account. Each name is separated by the given character.
*
* @note: WAKE UP!
* Unlike all other gets, the string returned by gnc_account_get_full_name()
* must be freed by you the user !!!
* hack alert -- since it breaks the rule of string allocation, maybe this
* routine should not be in this library, but some utility library?
*/
gchar * gnc_account_get_full_name (const Account *account);
/** Retrieve the gains account used by this account for the indicated
* currency, creating and recording a new one if necessary.
*
* FIXME: There is at present no interface to designate an existing
* account, and the new account name is hard coded to
* "Orphaned Gains -- CUR"
*
* FIXME: There is no provision for creating separate accounts for
* anything other than currency, e.g. holding period of a security.
*/
Account * xaccAccountGainsAccount (Account *acc, gnc_commodity *curr);
/** 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. */
void dxaccAccountSetPriceSrc (Account *account, const char *src);
/** 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. */
const char * dxaccAccountGetPriceSrc (const Account *account);
/** @} */
/** @name 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.
@{
*/
/** Set the account's commodity */
void xaccAccountSetCommodity (Account *account, gnc_commodity *comm);
/** Get the account's commodity */
/*@ dependent @*/
gnc_commodity * xaccAccountGetCommodity (const Account *account);
/** Returns a gnc_commodity that is a currency, suitable for being a
Transaction's currency. The gnc_commodity is taken either from the current
account, or from the next parent account that has a gnc_commodity that is a
currency. If neither this account nor any of its parent has such a commodity
that is a currency, NULL is returned. In that case, you can use
gnc_default_currency() but you might want to show a warning dialog first. */
gnc_commodity * gnc_account_get_currency_or_parent(const Account* account);
/** Return the SCU for the account. If a non-standard SCU has been
* set for the account, that is returned; else the default SCU for
* the account commodity is returned.
*/
int xaccAccountGetCommoditySCU (const Account *account);
/** Return the 'internal' SCU setting. This returns the over-ride
* SCU for the account (which might not be set, and might be zero). */
int xaccAccountGetCommoditySCUi (const Account *account);
/** Set the SCU for the account. Normally, this routine is not
* required, as the default SCU for an account is given by its
* commodity.
*/
void xaccAccountSetCommoditySCU (Account *account, int frac);
/** Set the flag indicating that this account uses a non-standard SCU. */
void xaccAccountSetNonStdSCU (Account *account, gboolean flag);
/** Return boolean, indicating whether this account uses a
* non-standard SCU. */
gboolean xaccAccountGetNonStdSCU (const Account *account);
/**@}*/
/** @name Account Balance
@{
*/
/** Get the current balance of the account, which may include future
splits */
gnc_numeric xaccAccountGetBalance (const Account *account);
/** Get the current balance of the account, only including cleared
transactions */
gnc_numeric xaccAccountGetClearedBalance (const Account *account);
/** Get the current balance of the account, only including reconciled
transactions */
gnc_numeric xaccAccountGetReconciledBalance (const Account *account);
gnc_numeric xaccAccountGetPresentBalance (const Account *account);
gnc_numeric xaccAccountGetProjectedMinimumBalance (const Account *account);
/** Get the balance of the account as of the date specified */
gnc_numeric xaccAccountGetBalanceAsOfDate (Account *account,
time64 date);
/** Get the reconciled balance of the account as of the date specified */
gnc_numeric xaccAccountGetReconciledBalanceAsOfDate (Account *account, time64 date);
/* These two functions convert a given balance from one commodity to
another. The account argument is only used to get the Book, and
may have nothing to do with the supplied balance. Likewise, the
date argument is only used for commodity conversion and may have
nothing to do with supplied balance.
Since they really have nothing to do with Accounts, there's
probably some better place for them, but where? gnc-commodity.h?
*/
gnc_numeric xaccAccountConvertBalanceToCurrency(
const Account *account, /* for book */
gnc_numeric balance,
const gnc_commodity *balance_currency,
const gnc_commodity *new_currency);
gnc_numeric xaccAccountConvertBalanceToCurrencyAsOfDate(
const Account *account, /* for book */
gnc_numeric balance, gnc_commodity *balance_currency,
gnc_commodity *new_currency, time64 date);
/* These functions get some type of balance in the desired commodity.
'report_commodity' may be NULL to use the account's commodity. */
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);
/* This function gets the balance as of the given date, ignoring
closing entries, in the desired commodity. */
gnc_numeric xaccAccountGetNoclosingBalanceAsOfDateInCurrency(
Account *acc, time64 date, gnc_commodity *report_commodity,
gboolean include_children);
/* This function gets the balance as of the given date in the desired
commodity. */
gnc_numeric xaccAccountGetBalanceAsOfDateInCurrency(
Account *account, time64 date, gnc_commodity *report_commodity,
gboolean include_children);
gnc_numeric xaccAccountGetNoclosingBalanceChangeForPeriod (
Account *acc, time64 date1, time64 date2, gboolean recurse);
gnc_numeric xaccAccountGetBalanceChangeForPeriod (
Account *acc, time64 date1, time64 date2, gboolean recurse);
/** @} */
/** @name 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.
@{
*/
/** 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).
*
* @param new_parent The new parent account to which the child should
* be attached.
*
* @param child The account to attach.
*/
void gnc_account_append_child (Account *new_parent, Account *child);
/** This function will remove the specified child account from the
* specified parent account. It will NOT free the associated memory
* or otherwise alter the account: the account can now be reparented
* to a new location. Note, however, that it will mark the old
* parents as having been modified.
*
* @param parent The parent account from which the child should be
* removed.
*
* @param child The child account to remove. */
void gnc_account_remove_child (Account *parent, Account *child);
/** This routine returns a pointer to the parent of the specified
* account. If the account has no parent, i.e it is either the root
* node or is a disconnected account, then its parent will be NULL.
*
* @param account A pointer to any exiting account.
*
* @return A pointer to the parent account node, or NULL if there is
* no parent account. */
/*@ dependent @*/
Account * gnc_account_get_parent (const Account *account);
/** This routine returns the root account of the account tree that the
* specified account belongs to. It is the equivalent of repeatedly
* calling the gnc_account_get_parent() routine until that routine
* returns NULL.
*
* @param account A pointer to any existing account.
*
* @return The root node of the account tree to which this account
* belongs. NULL if the account is not part of any account tree. */
Account * gnc_account_get_root (Account *account);
/** This routine indicates whether the specified account is the root
* node of an account tree.
*
* @param account A pointer to any account.
*
* @return TRUE if this account is of type ROOT. FALSE otherwise. */
gboolean gnc_account_is_root (const Account *account);
/** This routine returns a GList of all children accounts 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.
*
* If you are looking for the splits of this account, use
* xaccAccountGetSplitList() instead. This function here deals with
* children accounts inside the account tree.
*
* @param account The account whose children should be returned.
*
* @return A GList of account pointers, or NULL if there are no
* children accounts. It is the callers responsibility to free any returned
* list with the g_list_free() function. */
GList *gnc_account_get_children (const Account *account);
/** This routine returns a GList of all children accounts of the specified
* account, ordered by xaccAccountOrder(). \sa gnc_account_get_children()
*/
GList *gnc_account_get_children_sorted (const Account *account);
/** Return the number of children of the specified account. The
* returned number does not include the account itself.
*
* @param account The account to query.
*
* @return The number of children of the specified account. */
gint gnc_account_n_children (const Account *account);
/** 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.
*
* @param parent The parent account to check.
*
* @param child The child account to find.
*
* @return The index of the child account within the specified
* parent, or -1. */
gint gnc_account_child_index (const Account *parent, const Account *child);
/** Return the n'th child account of the specified parent account. If
* the parent account is not specified or the child index number is
* invalid, this function returns NULL.
*
* @param parent The parent account to check.
*
* @param num The index number of the child account that should be
* returned.
*
* @return A pointer to the specified child account, or NULL */
Account *gnc_account_nth_child (const Account *parent, gint num);
/** 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.
*
* @param account The account whose descendants should be returned.
*
* @return 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. */
GList * gnc_account_get_descendants (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.
*
* @param account The account whose descendants should be returned.
*
* @return 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. */
GList *gnc_account_get_descendants_sorted (const Account *account);
/** Return the number of descendants of the specified account. The
* returned number does not include the account itself.
*
* @param account The account to query.
*
* @return The number of descendants of the specified account. */
gint gnc_account_n_descendants (const Account *account);
/** Return the number of levels of this account below the root
* account.
*
* @param account The account to query.
*
* @return The number of levels below the root. */
gint gnc_account_get_current_depth (const Account *account);
/** Return the number of levels of descendants accounts below the
* specified account. The returned number does not include the
* specified account itself.
*
* @param account The account to query.
*
* @return The number of levels of descendants. */
gint gnc_account_get_tree_depth (const Account *account);
/** @name ForEach
@{
*/
/** 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.
*
* @param account A pointer to the account on whose children the
* function should be called.
*
* @param func A function taking two arguments, an Account and a
* gpointer.
*
* @param user_data This data will be passed to each call of func. */
void gnc_account_foreach_child (const Account *account,
AccountCb func, /*@ null @*/ 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.
*
* @param account A pointer to the account on whose descendants the
* function should be called.
*
* @param func A function taking two arguments, an Account and a
* gpointer.
*
* @param user_data This data will be passed to each call of func. */
void gnc_account_foreach_descendant (const Account *account,
AccountCb func, /*@ null @*/ 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 if
* func returns null for every account. For a simpler function that
* always traverses all children nodes, use the
* gnc_account_foreach_descendant() function.
*
* @param account A pointer to the account on whose descendants the
* function should be called.
*
* @param func A function taking two arguments, an Account and a
* gpointer.
*
* @param user_data This data will be passed to each call of func. */
gpointer gnc_account_foreach_descendant_until (const Account *account,
AccountCb2 func, /*@ null @*/ gpointer user_data);
/** @} */
/** @name Concatenation, Merging
@{
*/
/** The gnc_account_join_children() subroutine will move (reparent)
* all child accounts from the from_parent account to the to_parent
* account, preserving the account hierarchy. It will also take care
* that the moved accounts will have the to_parent's book parent
* as well.
*/
void gnc_account_join_children (Account *to_parent, Account *from_parent);
/** The gnc_account_merge_children() subroutine will go through an
* account, merging all child accounts that have the same name and
* description. This function is useful when importing Quicken(TM)
* files.
*/
void gnc_account_merge_children (Account *parent);
/** @} */
/** DOCUMENT ME! */
void xaccAccountSetReconcileChildrenStatus(Account *account, gboolean status);
/** DOCUMENT ME! */
gboolean xaccAccountGetReconcileChildrenStatus(const Account *account);
/** Returns true if the account is 'ancestor' or has 'ancestor' as an
* ancestor. An ancestor account may be the accounts parent, its
* parent's parent, its parent's parent's parent, etc. Returns false
* if either one is NULL.
*/
gboolean xaccAccountHasAncestor(const Account *acc, const Account *ancestor);
/** @} */
/** @name Lookup Accounts and Subaccounts by name or code
@{
*/
/** The gnc_account_lookup_by_name() subroutine fetches the account by
* name from the descendants of the specified account. The immediate
* children are searched first. If there is no match,, then a
* recursive search of all descendants is performed looking for a
* match.
*
* @return A pointer to the account with the specified name, or NULL
* if the account was not found.
*/
Account *gnc_account_lookup_by_name (const Account *parent, const char *name);
/** The gnc_account_lookup_full_name() subroutine works like
* gnc_account_lookup_by_name, but uses fully-qualified names using the
* given separator.
*/
Account *gnc_account_lookup_by_full_name (const Account *any_account,
const gchar *name);
/** The gnc_account_lookup_by_code() subroutine works like
* gnc_account_lookup_by_name, but uses the account code.
*/
Account *gnc_account_lookup_by_code (const Account *parent,
const char *code);
/** @} */
/* ------------------ */
/** @name GNCAccountType conversion/checking
@{
*/
/**
* Conversion routines for the account types to/from strings
* that are used in persistent storage, communications. These
* strings should *not* be translated to the local language.
* Typical conversion is ACCT_TYPE_INCOME -> "INCOME". */
const char * xaccAccountTypeEnumAsString (GNCAccountType type);
/**
* Conversion routines for the account types to/from strings
* that are used in persistent storage, communications. These
* strings should *not* be translated to the local language.
* Typical conversion is "INCOME" -> ACCT_TYPE_INCOME. */
gboolean xaccAccountStringToType (const char* str, GNCAccountType *type);
/**
* Conversion routines for the account types to/from strings
* that are used in persistent storage, communications. These
* strings should *not* be translated to the local language.
* Typical conversion is "INCOME" -> ACCT_TYPE_INCOME. */
GNCAccountType xaccAccountStringToEnum (const char* str);
/** The xaccAccountGetTypeStr() routine returns a string suitable for
* use in the GUI/Interface. These strings should be translated
* to the local language. */
const char * xaccAccountGetTypeStr (GNCAccountType type);
/** Return the bitmask of account types compatible with a given type.
* That is, you could switch to any of the account types in the compatible
* list without unwanted side-effects. */
guint32 xaccAccountTypesCompatibleWith (GNCAccountType type);
/** Return the bitmask of parent account types compatible with a given type. */
guint32 xaccParentAccountTypesCompatibleWith (GNCAccountType type);
/** Return TRUE if accounts of type parent_type can have accounts
* of type child_type as children. */
gboolean xaccAccountTypesCompatible (GNCAccountType parent_type,
GNCAccountType child_type);
/** Returns the bitmask of the account type enums that are valid. Deprecated and
* root account types are stripped. */
guint32 xaccAccountTypesValid(void);
/** Convenience function to check if the account is a valid
* Asset or Liability type, but not a business account type
* (meaning not an Accounts Payable/Accounts Receivable). */
gboolean xaccAccountIsAssetLiabType(GNCAccountType t);
/** Convenience function to return the fundamental type
* asset/liability/income/expense/equity given an account type. */
GNCAccountType xaccAccountTypeGetFundamental (GNCAccountType t);
/** Convenience function to check if the account is a valid
* business account type
* (meaning an Accounts Payable/Accounts Receivable). */
gboolean xaccAccountIsAPARType(GNCAccountType t);
/** Convenience function to check if the account is a valid
* Equity type. */
gboolean xaccAccountIsEquityType(GNCAccountType t);
/** @} */
/* ------------------ */
/** @name Account split/transaction list management
@{