1 /********************************************************************\ 2 * This program is free software; you can redistribute it and/or * 3 * modify it under the terms of the GNU General Public License as * 4 * published by the Free Software Foundation; either version 2 of * 5 * the License, or (at your option) any later version. * 6 * * 7 * This program is distributed in the hope that it will be useful, * 8 * but WITHOUT ANY WARRANTY; without even the implied warranty of * 9 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * 10 * GNU General Public License for more details. * 11 * * 12 * You should have received a copy of the GNU General Public License* 13 * along with this program; if not, contact: * 14 * * 15 * Free Software Foundation Voice: +1-617-542-5942 * 16 * 51 Franklin Street, Fifth Floor Fax: +1-617-542-2652 * 17 * Boston, MA 02110-1301, USA gnu@gnu.org * 18 * * 19 \********************************************************************/ 20 /** @addtogroup Engine 21 @{ */ 22 /** @addtogroup Transaction Transaction, Split 23 A good overview of transactions, splits and accounts can be 24 found in the texinfo documentation, together with an overview of 25 how to use this API. 26 27 @{ */ 28 /** @file Split.h 29 @brief API for Transactions and Splits (journal entries) 30 @author Copyright (C) 1997 Robin D. Clark 31 @author Copyright (C) 1997-2001 Linas Vepstas <linas@linas.org> 32 */ 33 34 #ifndef XACC_SPLIT_H 35 #define XACC_SPLIT_H 36 37 typedef struct _SplitClass SplitClass; 38 39 #include <time.h> 40 41 #include "gnc-commodity.h" 42 #include "gnc-engine.h" 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 48 /* --- type macros --- */ 49 #define GNC_TYPE_SPLIT (gnc_split_get_type ()) 50 #define GNC_SPLIT(o) \ 51 (G_TYPE_CHECK_INSTANCE_CAST ((o), GNC_TYPE_SPLIT, Split)) 52 #define GNC_SPLIT_CLASS(k) \ 53 (G_TYPE_CHECK_CLASS_CAST((k), GNC_TYPE_SPLIT, SplitClass)) 54 #define GNC_IS_SPLIT(o) \ 55 (G_TYPE_CHECK_INSTANCE_TYPE ((o), GNC_TYPE_SPLIT)) 56 #define GNC_IS_SPLIT_CLASS(k) \ 57 (G_TYPE_CHECK_CLASS_TYPE ((k), GNC_TYPE_SPLIT)) 58 #define GNC_SPLIT_GET_CLASS(o) \ 59 (G_TYPE_INSTANCE_GET_CLASS ((o), GNC_TYPE_SPLIT, SplitClass)) 60 GType gnc_split_get_type(void); 61 62 63 /** @name Split Reconciled field values 64 65 If you change these 66 be sure to change gnc-ui-util.c:gnc_get_reconciled_str() and 67 associated functions 68 69 @{ 70 */ 71 #define CREC 'c' /**< The Split has been cleared */ 72 #define YREC 'y' /**< The Split has been reconciled */ 73 #define FREC 'f' /**< frozen into accounting period */ 74 #define NREC 'n' /**< not reconciled or cleared */ 75 #define VREC 'v' /**< split is void */ 76 /** @} */ 77 78 /* Convert the amount/value of the Split for viewing in the account -- 79 * in particular we want to convert the Split to be in to_commodity. 80 * Returns the amount. 81 */ 82 gnc_numeric xaccSplitConvertAmount (const Split *split, const Account * account); 83 84 /*----------------------------------------------------------------------- 85 * Splits 86 *-----------------------------------------------------------------------*/ 87 88 /** @name Split general getters/setters 89 @{ 90 */ 91 92 /** Constructor. */ 93 Split * xaccMallocSplit (QofBook *book); 94 95 /* Reinit a previously malloc'd split. Split remains in the book it 96 was already in, and the QofInstance portions also remain unchanged. 97 It's basically the data elements that are reverted to default 98 values. */ 99 void xaccSplitReinit(Split * split); 100 101 /** Destructor. 102 * 103 * The xaccSplitDestroy() method will update its parent account and 104 * transaction in a consistent manner, resulting in the complete 105 * unlinking of the split, and the freeing of its associated memory. 106 * The goal of this routine is to perform the removal and destruction 107 * of the split in an atomic fashion, with no chance of accidentally 108 * leaving the accounting structure out-of-balance or otherwise 109 * inconsistent. 110 * 111 * If the deletion of the split leaves the transaction with no splits, 112 * then the transaction will be marked for deletion. (It will not be 113 * deleted until the xaccTransCommitEdit() routine is called.) 114 * 115 * @return TRUE upon successful deletion of the split. FALSE when 116 * the parenting Transaction is a read-only one. 117 */ 118 gboolean xaccSplitDestroy (Split *split); 119 120 /*################## Added for Reg2 #################*/ 121 /** This is really a helper for xaccTransCopyOnto. It doesn't reparent 122 * the 'to' split to from's transaction, because xaccTransCopyOnto is 123 * responsible for parenting the split to the correct transaction. 124 * Also, from's parent transaction may not even be a valid 125 * transaction, so this function may not modify anything about 'from' 126 * or from's transaction. 127 */ 128 void xaccSplitCopyOnto(const Split *from_split, Split *to_split); 129 /*################## Added for Reg2 #################*/ 130 131 /** Returns the book of this split, i.e. the entity where this split 132 * is stored. */ 133 QofBook * xaccSplitGetBook (const Split *split); 134 135 /** Returns the account of this split, which was set through 136 * xaccAccountInsertSplit(). */ 137 Account * xaccSplitGetAccount (const Split *split); 138 void xaccSplitSetAccount (Split *s, Account *acc); 139 140 /** Returns the parent transaction of the split. */ 141 Transaction * xaccSplitGetParent (const Split *split); 142 void xaccSplitSetParent (Split *split, Transaction *trans); 143 144 /** Returns the pointer to the debited/credited Lot where this split 145 * belongs to, or NULL if it doesn't belong to any. */ 146 GNCLot * xaccSplitGetLot (const Split *split); 147 148 /** Assigns the split to a specific Lot */ 149 void xaccSplitSetLot(Split* split, GNCLot* lot); 150 151 /** The memo is an arbitrary string associated with a split. It is 152 * intended to hold a short (zero to forty character) string that is 153 * displayed by the GUI along with this split. Users typically type 154 * in free form text from the GUI. */ 155 void xaccSplitSetMemo (Split *split, const char *memo); 156 157 /** Returns the memo string. */ 158 const char * xaccSplitGetMemo (const Split *split); 159 160 /** The Action is an arbitrary user-assigned string. 161 * The action field is an arbitrary user-assigned value. 162 * It is meant to be a very short (one to ten character) string that 163 * signifies the "type" of this split, such as e.g. Buy, Sell, Div, 164 * Withdraw, Deposit, ATM, Check, etc. The idea is that this field 165 * can be used to create custom reports or graphs of data. Note that the 166 * business features auto-fill this value, but doesn't depend on it. Rather than use 167 * this function directly, see 'gnc_set_num_action' in 168 * engine/engine-helpers.c & .h which takes a user-set book option for selecting 169 * the source for the num-cell (the transaction-number or the split-action field) 170 * in registers/reports into account automatically */ 171 void xaccSplitSetAction (Split *split, const char *action); 172 173 /** Returns the action string. Rather than use this function directly, see 174 * 'gnc_get_num_action' and 'gnc_get_action_num'in 175 * engine/engine-helpers.c & .h which takes a user-set book option for selecting 176 * the source for the num-cell (the transaction-number or the split-action field) 177 * in registers/reports into account automatically */ 178 const char * xaccSplitGetAction (const Split *split); 179 /** @} */ 180 181 /** @name Split Date getters/setters 182 @{ 183 */ 184 /** Set the reconcile flag. The Reconcile flag is a single char, whose 185 * values are typically are 'n', 'y', 'c'. In Transaction.h, macros 186 * are defined for typical values (e.g. CREC, YREC). */ 187 void xaccSplitSetReconcile (Split *split, char reconciled_flag); 188 /** Returns the value of the reconcile flag. */ 189 char xaccSplitGetReconcile (const Split *split); 190 191 /** Set the date on which this split was reconciled by specifying the 192 * time as time64. */ 193 void xaccSplitSetDateReconciledSecs (Split *split, time64 time); 194 195 /*################## Added for Reg2 #################*/ 196 /** Retrieve the date when the Split was reconciled. */ 197 time64 xaccSplitGetDateReconciled (const Split *split); 198 /*################## Added for Reg2 #################*/ 199 200 /** @} */ 201 202 203 /** @name Split amount getters/setters 204 * 205 * 'value' vs. 'amount' of a Split: The 'value' is the amount of the 206 * _transaction_ balancing commodity (i.e. currency) involved, 207 * 'amount' is the amount of the _account's_ commodity involved. 208 @{ 209 */ 210 211 /** The xaccSplitSetAmount() method sets the amount in the account's 212 * commodity that the split should have. 213 * 214 * The following four setter functions set the prices and amounts. 215 * All of the routines always maintain balance: that is, invoking any 216 * of them will cause other splits in the transaction to be modified 217 * so that the net value of the transaction is zero. 218 * 219 * IMPORTANT: The split should be parented by an account before 220 * any of these routines are invoked! This is because the actual 221 * setting of amounts/values requires SCU settings from the account. 222 * If these are not available, then amounts/values will be set to 223 * -1/0, which is an invalid value. I believe this order dependency 224 * is a bug, but I'm too lazy to find, fix & test at the moment ... 225 * 226 * @note If you use this on a newly created transaction, make sure 227 * that the 'value' is also set so that it doesn't remain zero. 228 */ 229 void xaccSplitSetAmount (Split *split, gnc_numeric amount); 230 231 /** Returns the amount of the split in the account's commodity. 232 * Note that for cap-gains splits, this is slaved to the transaction 233 * that is causing the gains to occur. 234 */ 235 gnc_numeric xaccSplitGetAmount (const Split * split); 236 237 /** The xaccSplitSetValue() method sets the value of this split in the 238 * transaction's commodity. 239 * 240 * @note If you use this on a newly created transaction, make sure 241 * that the 'amount' is also set so that it doesn't remain zero. 242 */ 243 void xaccSplitSetValue (Split *split, gnc_numeric value); 244 245 /** Returns the value of this split in the transaction's commodity. 246 * Note that for cap-gains splits, this is slaved to the transaction 247 * that is causing the gains to occur. 248 */ 249 gnc_numeric xaccSplitGetValue (const Split * split); 250 251 /** The xaccSplitSetSharePriceAndAmount() method will simultaneously 252 * update the share price and the number of shares. This is a utility 253 * routine that is equivalent to a xaccSplitSetSharePrice() followed 254 * by and xaccSplitSetAmount(), except that it incurs the processing 255 * overhead of balancing only once, instead of twice. */ 256 void xaccSplitSetSharePriceAndAmount (Split *split, 257 gnc_numeric price, 258 gnc_numeric amount); 259 260 /** Returns the price of the split, that is, the value divided by the 261 * amount. If the amount is zero, returns a gnc_numeric of value 262 * one. */ 263 gnc_numeric xaccSplitGetSharePrice (const Split * split); 264 265 /** Depending on the base_currency, set either the value or the amount 266 * of this split or both: If the base_currency is the transaction's 267 * commodity, set the value. If it is the account's commodity, set the 268 * amount. If both, set both. 269 * 270 * @note <b>WATCH OUT:</b> When using this function and the 271 * transaction's and account's commodities are different, the amount 272 * or the value will be left as zero. This might screw up the 273 * multi-currency handling code in the register. So please think twice 274 * whether you need this function -- using xaccSplitSetValue() 275 * together with xaccSplitSetAmount() is definitely the better and 276 * safer solution! 277 */ 278 void xaccSplitSetBaseValue (Split *split, gnc_numeric value, 279 const gnc_commodity * base_currency); 280 281 /** Depending on the base_currency, return either the value or the 282 * amount of this split: If the base_curreny is the transaction's 283 * commodity, return the value. If it is the account's commodity, 284 * return the amount. If it is neither print a warning message and 285 * return gnc_numeric_zero(). 286 */ 287 gnc_numeric xaccSplitGetBaseValue (const Split *split, 288 const gnc_commodity * base_currency); 289 290 /** Returns the running balance up to and including the indicated split. 291 * The balance is the currency-denominated balance. For accounts 292 * with non-unit share prices, it is correctly adjusted for 293 * share prices. 294 * 295 * Returns the running balance up to & including the indicated split. 296 */ 297 gnc_numeric xaccSplitGetBalance (const Split *split); 298 299 /** 300 * The noclosing-balance is the currency-denominated balance of all 301 * transactions except 'closing' transactions. It is correctly 302 * adjusted for price fluctuations. 303 * 304 * Returns the running balance up to & including the indicated split. 305 */ 306 gnc_numeric xaccSplitGetNoclosingBalance (const Split *split); 307 308 /** 309 * The cleared-balance is the currency-denominated balance 310 * of all transactions that have been marked as cleared or reconciled. 311 * It is correctly adjusted for price fluctuations. 312 * 313 * Returns the running balance up to & including the indicated split. 314 */ 315 gnc_numeric xaccSplitGetClearedBalance (const Split *split); 316 317 /** 318 * Returns the reconciled-balance of this split. The 319 * reconciled-balance is the currency-denominated balance of all 320 * transactions that have been marked as reconciled. 321 * 322 * Returns the running balance up to & including the indicated split. 323 */ 324 gnc_numeric xaccSplitGetReconciledBalance (const Split *split); 325 326 /** @} */ 327 328 /** @name Split utility functions 329 @{ 330 */ 331 332 /** Equality. 333 * 334 * @param sa First split to compare 335 * @param sb Second split to compare 336 * 337 * @param check_guids If TRUE, try a guid_equal() on the GUIDs of both 338 * splits if their pointers are not equal in the first place. 339 * 340 * @param check_balances If TRUE, compare balances between the two 341 * splits. Balances are recalculated whenever a split is added or 342 * removed from an account, so YMMV on whether this should be set. 343 * 344 * @param check_txn_splits If the pointers are not equal, but 345 * everything else so far is equal (including memo, amount, value, 346 * kvp), then, when comparing the parenting transactions with 347 * xaccTransEqual(), set its argument check_splits to be TRUE. 348 */ 349 gboolean xaccSplitEqual(const Split *sa, const Split *sb, 350 gboolean check_guids, 351 gboolean check_balances, 352 gboolean check_txn_splits); 353 354 /** The xaccSplitLookup() subroutine will return the 355 * split associated with the given id, or NULL 356 * if there is no such split. */ 357 Split * xaccSplitLookup (const GncGUID *guid, QofBook *book); 358 #define xaccSplitLookupDirect(g,b) xaccSplitLookup(&(g),b) 359 360 /*################## Added for Reg2 #################*/ 361 /* Get a GList of unique transactions containing the given list of Splits. */ 362 GList *xaccSplitListGetUniqueTransactionsReversed (const GList *splits); 363 GList *xaccSplitListGetUniqueTransactions(const GList *splits); 364 /*################## Added for Reg2 #################*/ 365 /** Add a peer split to this split's lot-split list. 366 * @param other_split: The split whose guid to add 367 * @param timestamp: The time to be recorded for the split. 368 */ 369 void xaccSplitAddPeerSplit (Split *split, const Split *other_split, 370 const time64 timestamp); 371 /** Does this split have peers? 372 */ 373 gboolean xaccSplitHasPeers (const Split *split); 374 /** Report if a split is a peer of this one. 375 * @param other_split: The split to test for being a peer of this one. 376 * @return: True if other_split is registered as a peer of this one. 377 */ 378 gboolean xaccSplitIsPeerSplit (const Split *split, const Split *other_split); 379 /** Remove a peer split from this split's lot-split list. 380 * @param other_split: The split whose guid to remove 381 */ 382 void xaccSplitRemovePeerSplit (Split *split, const Split *other_split); 383 384 /** Merge the other_split's peer splits into split's peers. 385 * @param other_split: The split donating the peer splits. 386 */ 387 void xaccSplitMergePeerSplits (Split *split, const Split *other_split); 388 389 /** 390 * The xaccSplitGetOtherSplit() is a convenience routine that returns 391 * the other of a pair of splits. If there are more than two 392 * splits, it returns NULL. 393 */ 394 Split * xaccSplitGetOtherSplit (const Split *split); 395 396 /** The xaccIsPeerSplit() is a convenience routine that returns TRUE 397 * (a non-zero value) if the two splits share a common parent 398 * transaction, else it returns FALSE (zero). 399 * 400 gboolean xaccIsPeerSplit (const Split *split_1, const Split *split_2); 401 */ 402 /** Returns the split type, which is either the string "normal", or 403 * "stock-split" for a split from a stock split (pun intended? :-). */ 404 const char *xaccSplitGetType(const Split *s); 405 406 /** Mark a split to be of type stock split - after this, you shouldn't 407 modify the value anymore, just the amount. */ 408 void xaccSplitMakeStockSplit(Split *s); 409 410 /** 411 * The xaccSplitOrder(sa,sb) method is useful for sorting. 412 * if sa and sb have different transactions, return their xaccTransOrder 413 * return a negative value if split sa has a smaller currency-value than sb, 414 * return a positive value if split sa has a larger currency-value than sb, 415 * return a negative value if split sa has a smaller share-price than sb, 416 * return a positive value if split sa has a larger share-price than sb, 417 * then compares memo and action using the strcmp() 418 * c-library routine, returning what strcmp would return. 419 * Then it compares the reconciled flags, then the reconciled dates, 420 * Finally, it returns zero if all of the above match. 421 */ 422 gint xaccSplitOrder (const Split *sa, const Split *sb); 423 gint xaccSplitOrderDateOnly (const Split *sa, const Split *sb); 424 425 426 /* 427 * These functions compare two splits by different criteria. 428 * 429 * These functions were added because converting strings to guile 430 * for comparisons in the transaction report is terribly inefficient. 431 * More may be added here in future if it turns out that other types 432 * of comparisons also induces guile slowdowns. 433 */ 434 435 /** Compare two splits by full name of account. Returns similar to 436 * strcmp. */ 437 int xaccSplitCompareAccountFullNames(const Split *sa, const Split *sb); 438 /** Compare two splits by code of account. Returns similar to 439 * strcmp. */ 440 int xaccSplitCompareAccountCodes(const Split *sa, const Split *sb); 441 /** Compare two splits by full name of the other account. Returns 442 * similar to strcmp. This function attempts to find the split on the 443 * other side of a transaction and compare on it. */ 444 int xaccSplitCompareOtherAccountFullNames(const Split *sa, const Split *sb); 445 /** Compare two splits by code of the other account. Returns similar 446 * to strcmp. This function attempts to find the split on the 447 * other side of a transaction and compare on it. */ 448 int xaccSplitCompareOtherAccountCodes(const Split *sa, const Split *sb); 449 450 451 /** 452 * These functions take a split, get the corresponding split on the 453 * "other side" of the transaction, and extract either the name or code 454 * of that split, reverting to returning a constant "Split" if the 455 * transaction has more than one split on the "other side". These 456 * were added for the transaction report, and is in C because the code 457 * was already written in C for the above functions and duplication 458 * is silly. 459 * 460 * Note that this will only return a real value in case of a 461 * two-split transaction as that is the only situation in which 462 * a reliable value can be returned. In other situations 463 * "-- Split Transaction --" will be returned as Account Name 464 * or "Split" for Account Code. 465 */ 466 467 char * xaccSplitGetCorrAccountFullName(const Split *sa); 468 /** document me */ 469 const char * xaccSplitGetCorrAccountName(const Split *sa); 470 /** document me */ 471 const char * xaccSplitGetCorrAccountCode(const Split *sa); 472 473 #ifdef DUMP_FUNCTIONS 474 void xaccSplitDump (const Split *split, const char *tag); 475 #endif 476 477 /** @} */ 478 479 480 481 /** @name Split deprecated functions 482 @{ 483 */ 484 485 /** @deprecated The xaccSplitSetSharePrice() method sets the price of the 486 * split. DEPRECATED - set the value and amount instead. */ 487 void xaccSplitSetSharePrice (Split *split, gnc_numeric price); 488 489 /** @} */ 490 491 492 /********************************************************************\ 493 * Miscellaneous utility routines. 494 \********************************************************************/ 495 496 497 /** @name Split voiding 498 @{ 499 */ 500 501 /** Returns the original pre-void amount of a split. 502 * 503 * @param split The split in question. 504 * 505 * @return A gnc_numeric containing the original value of this split. 506 * Returns a gnc_numeric of zero upon error. 507 */ 508 gnc_numeric xaccSplitVoidFormerAmount(const Split *split); 509 510 /** Returns the original pre-void value of a split. 511 * 512 * @param split The split in question. 513 * 514 * @return A gnc_numeric containing the original amount of this split. 515 * Returns a gnc_numeric of zero upon error. 516 */ 517 gnc_numeric xaccSplitVoidFormerValue(const Split *split); 518 519 /** @} */ 520 521 /** @name Split Parameter names 522 523 * Note, if you want to get the equivalent of "ACCT_MATCH_ALL" you 524 * need to create a search on the following parameter list: 525 * SPLIT->SPLIT_TRANS->TRANS_SPLITLIST->SPLIT_ACCOUNT_GUID. If you do 526 * this, you might want to use the ACCOUNT_MATCH_ALL_TYPE as the 527 * override so the gnome-search dialog displays the right type. 528 @{ 529 */ 530 #define SPLIT_DATE_RECONCILED "date-reconciled" 531 #define SPLIT_BALANCE "balance" 532 #define SPLIT_CLEARED_BALANCE "cleared-balance" 533 #define SPLIT_RECONCILED_BALANCE "reconciled-balance" 534 #define SPLIT_MEMO "memo" 535 #define SPLIT_ACTION "action" 536 #define SPLIT_RECONCILE "reconcile-flag" 537 #define SPLIT_AMOUNT "amount" 538 #define SPLIT_SHARE_PRICE "share-price" 539 #define SPLIT_VALUE "value" 540 #define SPLIT_TYPE "type" 541 #define SPLIT_VOIDED_AMOUNT "voided-amount" 542 #define SPLIT_VOIDED_VALUE "voided-value" 543 #define SPLIT_LOT "lot" 544 #define SPLIT_TRANS "trans" 545 #define SPLIT_ACCOUNT "account" 546 #define SPLIT_ACCOUNT_GUID "account-guid" /**< for guid_match_all */ 547 /* used for SORTING ONLY */ 548 #define SPLIT_ACCT_FULLNAME "acct-fullname" 549 #define SPLIT_CORR_ACCT_NAME "corr-acct-fullname" 550 #define SPLIT_CORR_ACCT_CODE "corr-acct-code" 551 /** @} */ 552 553 /** \deprecated */ 554 #define xaccSplitGetGUID(X) qof_entity_get_guid(QOF_INSTANCE(X)) 555 /** \deprecated */ 556 #define xaccSplitReturnGUID(X) (X ? *(qof_entity_get_guid(QOF_INSTANCE(X))) : *(guid_null())) 557 558 #ifdef __cplusplus 559 } /* extern "C" */ 560 #endif 561 562 #endif /* XACC_SPLIT_H */ 563 /** @} */ 564 /** @} */ 565