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

@@ -3,6 +3,7 @@ COPYING
 INSTALL
 Makefile
 Makefile.in
+TAGS
 aclocal.m4
 configure
 config.cache

ChangeLog

@@ -1,3 +1,21 @@
+2001-01-03  Rob Browning  <rlb@cs.utexas.edu>
+
+	* 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  <grib@billgribble.com>
 
 	* src/scm/report.scm: minor changes to allow report URLs

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

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);
+}
+
+
 /********************************************************************\
 \********************************************************************/
 

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
  *