From 9b07ec0629af7b44418d75a8497ab67bca312ccf Mon Sep 17 00:00:00 2001 From: Dave Peticolas Date: Sat, 23 Sep 2000 10:11:55 +0000 Subject: [PATCH] Update docs. git-svn-id: svn+ssh://svn.gnucash.org/repo/gnucash/trunk@2933 57a11ea4-9604-0410-9ed3-97b8803252fd --- src/doc/design/engine.texinfo | 59 +++++++++++++++++++++++++++++++++++ src/engine/Transaction.h | 31 ++++++++---------- 2 files changed, 72 insertions(+), 18 deletions(-) diff --git a/src/doc/design/engine.texinfo b/src/doc/design/engine.texinfo index e6f62b55c1..7fae6350a5 100644 --- a/src/doc/design/engine.texinfo +++ b/src/doc/design/engine.texinfo @@ -671,6 +671,18 @@ user input. Allocate, initialize, and return a new Split. @end deftypefun +@deftypefun void xaccSplitDestroy (Split * @var{split}) +Update @var{split}'s parent Account and Transaction in a consistent +manner, completely unlinking of @var{split} and freeing its memory. The +goal of this routine is to perform the removal and destruction of the +Split in an atomic fashion, with no chance of accidentally leaving the +accounting structure out-of-balance or otherwise inconsistent. + +If the deletion of the Split leaves the Transaction with no Splits, then +the Transaction will be marked for deletion, but will not be deleted +until the @code{xaccTransCommitEdit()} routine is called. +@end deftypefun + @deftypefun {const GUID *} xaccSplitGetGUID (Split * @var{split}) Return the GUID of @var{split}. @end deftypefun @@ -924,6 +936,50 @@ for editing. Allocate, initialize, and return a new Transaction. @end deftypefun +@deftypefun void xaccTransAppendSplit (Transaction * @var{trans}, Split * @var{split}) +Append @var{split} to the collection of Splits in @var{trans}. If the +Split is already a part of another Transaction, it will be removed from +that Transaction first. +@end deftypefun + +@deftypefun void xaccTransDestroy (Transaction * {trans}) +Remove all of the Splits from each of their accounts and free the memory +associated with them. This routine must be followed by either an +@code{xaccTransCommitEdit()} in which case the transaction memory will +be freed, or by @code{xaccTransRollbackEdit()}, in which case all the +original Splits are put back into place. +@end deftypefun + +@deftypefun void xaccTransBeginEdit (Transaction * @var{trans}, gboolean @var{defer}) +This method must be called before any changes are made to @var{trans} or +any of its component Splits. If this is not done, errors will result. If +@var{defer} is true, then the automated re-balancing of all Splits in +this transaction is deferred until the @code{xaccTransCommitEdit()} +call. This allows multiple splits to be edited, quantities modified, +with the whole system temporarily out of balance, up until the +Commit call is made when double-entry is once again enforced. +@end deftypefun + +@deftypefun void xaccTransCommitEdit (Transaction * @var{trans}) +This method indicates that the changes to @var{trans} and its Splits are +complete and should be made permanent. Note this routine may result in +the deletion of the transaction, if the Transaction is "empty" (has no +Splits) or if @code{xaccTransDestroy()} was called on the Transaction. +@end deftypefun + +@deftypefun void xaccTransRollbackEdit (Transaction * @var{trans}) +Rejects all changes made to @var{trans} and its Splits, and sets +@var{trans} back to where it was before the @code{xaccTransBeginEdit()} +call. This includes restoring any deleted Splits, removing any added +Splits, and undoing the effects of @code{xaccTransDestroy()}, as well +as restoring share quantities, memos, descriptions, etc. +@end deftypefun + +@deftypefun gboolean xaccTransIsOpen (Transaction * @var{trans}) +Return @code{TRUE} if @var{trans} is open for editing. Otherwise, it +returns @code{FALSE}. +@end deftypefun + @deftypefun {const GUID *} xaccTransGetGUID (Transaction * @var{trans}) Return the GUID of @var{trans}. @end deftypefun @@ -988,6 +1044,9 @@ Return the number of Splits in @var{trans}. @node Transaction Setters, , Transaction Getters, Transactions @subsection Transaction Setters +Remember, before you modify a Transaction, you must open it for editing +with @code{xaccTransBeginEdit}. + @deftypefun void xaccTransSetDate (Transaction * @var{trans}, int @var{day}, int @var{mon}, int @var{year}) Set the post date of @var{trans} with @var{day}, @var{month}, and @var{year}. @end deftypefun diff --git a/src/engine/Transaction.h b/src/engine/Transaction.h index a704ed312d..2ecf7edeb6 100644 --- a/src/engine/Transaction.h +++ b/src/engine/Transaction.h @@ -93,26 +93,24 @@ void xaccTransDestroy (Transaction *trans); * this is not done, errors will result. If the defer flag is set, * then the automated re-balancing of all splits in this transaction * is deferred until the xaccTransCommitEdit() call. This allows - * multiple splits to be edited, and prices fiddled with, and the whole - * system sent temporarily out of balance, up until the Commit + * multiple splits to be edited, and quantities modified, and the + * whole system temporarily out of balance, up until the Commit * call is made when double-entry is once again enforced. * - * The xaccTransCommitEdit() method should be used to indicate that - * all of the manipulations on the transaction are complete, and - * that these should be made permanent. Note that this routine - * may result in the deletion of the transaction, if the transaction - * is "empty" (has no splits, or * has a single split in it whose - * value is non-zero.) + * The xaccTransCommitEdit() method indicates that the changes to the + * transaction and its splits are complete and should be made + * permanent. Note this routine may result in the deletion of the + * transaction, if the transaction is "empty" (has no splits), or + * of xaccTransDestroy() was called on the transaction. * * The xaccTransRollbackEdit() routine rejects all edits made, and * sets the transaction back to where it was before the editing * started. This includes restoring any deleted splits, removing * any added splits, and undoing the effects of xaccTransDestroy, - * as well as restoring prices, memo's descriptions, etc. + * as well as restoring share quantities, memos, descriptions, etc. * * The xaccTransIsOpen() method returns TRUE if the transaction - * is open for editing. Otherwise, it returns false. - */ + * is open for editing. Otherwise, it returns false. */ void xaccTransBeginEdit (Transaction *trans, gboolean defer); void xaccTransCommitEdit (Transaction *trans); void xaccTransRollbackEdit (Transaction *trans); @@ -197,13 +195,10 @@ void xaccTransAppendSplit (Transaction *trans, Split *split); * leaving the accounting structure out-of-balance or otherwise * inconsistent. * - * If the deletion of the split leaves the transaction "empty", - * then the transaction will be marked for deletion. (It will - * not be deleted until the xaccTransCommitEdit() routine is called.) - * The transaction is considered "empty" if it has no splits in it, - * or it has only one split left, and that split is not a price split - * (i.e. has a non-zero value). Transactions with only one split in - * them are valid if and only if the value of that split is zero. + * If the deletion of the split leaves the transaction with no + * splits, then the transaction will be marked for deletion. (It + * will not be deleted until the xaccTransCommitEdit() routine is + * called.) */ void xaccSplitDestroy (Split *split);