From 7eb2066592a1e7671fb1d5cc6dea168aec55b87e Mon Sep 17 00:00:00 2001 From: Dave Peticolas Date: Wed, 3 Jan 2001 23:33:08 +0000 Subject: [PATCH] Rob Browning's patch to add a 'type' api for Splits. git-svn-id: svn+ssh://svn.gnucash.org/repo/gnucash/trunk@3381 57a11ea4-9604-0410-9ed3-97b8803252fd --- .cvsignore | 1 + ChangeLog | 18 ++++++++++++ src/doc/design/engine.texinfo | 52 +++++++++++++++++++++++++---------- src/engine/Transaction.c | 35 ++++++++++++++++++++++- src/engine/Transaction.h | 16 +++++++++-- 5 files changed, 104 insertions(+), 18 deletions(-) diff --git a/.cvsignore b/.cvsignore index 20397625b6..cb8755ad49 100644 --- a/.cvsignore +++ b/.cvsignore @@ -3,6 +3,7 @@ COPYING INSTALL Makefile Makefile.in +TAGS aclocal.m4 configure config.cache diff --git a/ChangeLog b/ChangeLog index e615dd068f..8ef89b549a 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,21 @@ +2001-01-03 Rob Browning + + * src/engine/Transaction.h :start documenting reserved split slots. + add prototypes for new functions below. + + * src/engine/Transaction.c + (xaccSplitGetType): new function. + (xaccSplitMakeStockSplit): new function. + + * src/doc/design/engine.texinfo + (Engine Introduction): add docs for split types, including the new + stock-split split. + (General Split API): remove Slot Get/Set function docs. + (General Split API): add xaccSplitMakeStockSplit docs. + (Split Getters): add xaccSplitGetType docs. + + * .cvsignore: add TAGS. + 2000-12-20 Bill Gribble * src/scm/report.scm: minor changes to allow report URLs diff --git a/src/doc/design/engine.texinfo b/src/doc/design/engine.texinfo index 2e7d341553..22e85ddced 100644 --- a/src/doc/design/engine.texinfo +++ b/src/doc/design/engine.texinfo @@ -1,4 +1,4 @@ -@node Engine, Register, Top Level, Top +@node Engine @chapter Engine @cindex The Engine @@ -49,13 +49,13 @@ accounting. A Transaction consists of a date, a description, a number, a list of one or more Splits, and a key-value frame. When double-entry rules are enforced, the total value of the splits is zero. Note that if there is just one split, its value must be zero for double-entry -accounting; this is useful because a zero-valued split can store a price -(useful for e.g. tracking stocks). If there are two splits, then the -value of one must be positive, the other negative: this denotes that one -account is credited, and another is debited by an equal amount. Positive -Split values are 'debits' and negative Split values are 'credits'. -Ensuring the Splits to 'add up' to zero causes a double-entry accounting -system to always balance. +accounting; this used to be used for storing prices, but with the advent +of the pricedb, zero-valued splits are probably best avoided. If there +are two splits, then the value of one must be positive, the other +negative: this denotes that one account is credited, and another is +debited by an equal amount. Positive Split values are 'debits' and +negative Split values are 'credits'. Ensuring the Splits to 'add up' to +zero causes a double-entry accounting system to always balance. The engine does not enforce double-entry accounting, but provides an API to enable user-code to find unbalanced transactions and 'repair' them so @@ -1070,6 +1070,17 @@ reconciliation states for a Split are: @end table +@item A set of slots +This is a kvp_frame specific to a given split. Reserved key names +include: + + @table @code + @item "gnc:stock-split" + This slot stores a string indicating the type of the split if the + split is not a ``normal'' split. See @code{xaccSplitGetType} + for more details. + @end table + @end table In addition to the above, Splits contain a Memo field, an Action field, @@ -1111,13 +1122,9 @@ Return the split associated with @var{GUID}, or @code{NULL} if there is no such split. @end deftypefun -@deftypefun {kvp_value *} xaccSplitGetSlot(Split * @var{split}, const char * @var{key}) -Return the @code{kvp_value} associated with @var{key} in @var{split}. -If there is none, @code{NULL} is returned. -@end deftypefun - -@deftypefun void xaccSplitSetSlot(Split * @var{split}, const char * @var{key}, const kvp_value * @var{value}) -Associate a copy of @var{value} with @var{key} in @var{split}. +@deftypefun void xaccSplitMakeStockSplit (Split * @var{split}) +Modify @var{split} to be an ``official'' stock-split split. Among other +things, this involves clearing the value of the split to 0. @end deftypefun @@ -1216,6 +1223,21 @@ Return the share reconciled balance of @var{split}'s parent Account up to and including @var{split}. See @ref{Accounts} for details. @end deftypefun +@deftypefun {const char*} xaccSplitGetType (Split * @var{split}) +Return @var{split}'s type as a string. Currently, the possibilities are + + @table @code + @item normal + a normal split -- the default. + + @item stock-split + a split representing a stock split. The value should be 0 and the + share amount should represent the number of shares added/subtracted from + the account as a result of the forward/reverse stock split. + @end table + +@end deftypefun + @node Split Setters, , Split Getters, Splits @subsection Split Setters diff --git a/src/engine/Transaction.c b/src/engine/Transaction.c index 298a009349..532a634d1a 100644 --- a/src/engine/Transaction.c +++ b/src/engine/Transaction.c @@ -467,7 +467,7 @@ void xaccSplitSetValue (Split *s, gnc_numeric amt) { if(!s) return; - s->value = gnc_numeric_convert(amt, get_currency_denom(s), GNC_RND_ROUND);; + s->value = gnc_numeric_convert(amt, get_currency_denom(s), GNC_RND_ROUND); mark_split (s); } @@ -2055,6 +2055,39 @@ xaccSplitGetSharePrice (Split * split) { PRICE_DENOM, GNC_RND_ROUND); } +/********************************************************************\ +\********************************************************************/ + +const char * +xaccSplitGetType(const Split *s) +{ + kvp_frame *frame; + kvp_value *split_type; + + if(!s) return NULL; + frame = xaccSplitGetSlots((Split *) s); + if(!frame) return NULL; + split_type = kvp_frame_get_slot(frame, "gnc:split-type"); + if(!split_type) return "normal"; + if(kvp_value_get_type(split_type) != KVP_TYPE_STRING) return NULL; + return(kvp_value_get_string(split_type)); +} + +/* reconfgure a split to be a stock split - after this, you shouldn't + mess with the value, just the damount. */ +void +xaccSplitMakeStockSplit(Split *s) +{ + kvp_frame *frame = xaccSplitGetSlots(s); + + xaccSplitSetValue(s, gnc_numeric_zero()); + kvp_frame_set_slot(frame, + "gnc:split-type", + kvp_value_new_string("stock-split")); + mark_split(s); +} + + /********************************************************************\ \********************************************************************/ diff --git a/src/engine/Transaction.h b/src/engine/Transaction.h index aa90048deb..553973a30d 100644 --- a/src/engine/Transaction.h +++ b/src/engine/Transaction.h @@ -299,8 +299,13 @@ gboolean xaccSplitEqual(const Split *sa, const Split *sb, gboolean check_txn_splits); /* Split slots are used to store arbitrary strings, numbers, and - * structures which aren't members of the transaction struct. */ - + * structures which aren't members of the transaction struct. + * + * Reserved slot names: + * + * gnc:split-type -- a string representing the type of split, if not normal. + * + */ kvp_frame *xaccSplitGetSlots(Split *trans); /* The xaccSplitGetGUID() subroutine will return the @@ -426,6 +431,13 @@ gnc_numeric xaccSplitGetValue (Split * split); Account * xaccSplitGetAccount (Split *split); +/* split types: normal stock-split */ +const char *xaccSplitGetType(const Split *s); + +/* reconfgure a split to be a stock split - after this, you shouldn't + mess with the value, just the damount. */ +void xaccSplitMakeStockSplit(Split *s); + /********************************************************************\ * sorting comparison function *