Added documentation to balance_pair_t.

1 files changed, 100 insertions, 16 deletions

diff --git a/src/balpair.h b/src/balpair.h
index a4ba601f..1198a82f 100644
--- a/src/balpair.h
+++ b/src/balpair.h
@@ -29,6 +29,25 @@
  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+/**
+ * @file   balpair.h
+ * @author John Wiegley
+ * @date   Sun May 20 19:11:58 2007
+ * 
+ * @brief  Provides an abstraction around balance_t for tracking costs.
+ * 
+ * When a transaction's amount is added to a balance, only the "value"
+ * of the amount is added -- not the associated cost of the
+ * transaction.  To provide for this, the balance_pair_t type allows
+ * for adding amounts and costs simultaneously to a single balance.
+ * Both are tracked, and any time either the total amount balance or
+ * the total cost balance may be extracted.
+ *
+ * Note: By default, all balance-like operations operate on the amount
+ * balance, and not the cost.  Also, the cost is entirely optional, in
+ * which case a balance_pair_t may be used as if it were a balance_t,
+ * from which is it derived.
+ */
 #ifndef _BALPAIR_H
 #define _BARPAIR_H
 
@@ -40,48 +59,113 @@ class balance_pair_t
   : public equality_comparable<balance_pair_t,
            equality_comparable<balance_pair_t, balance_t,
            equality_comparable<balance_pair_t, amount_t,
+           equality_comparable<balance_pair_t, double,
+           equality_comparable<balance_pair_t, unsigned long,
+           equality_comparable<balance_pair_t, long,
            additive<balance_pair_t,
            additive<balance_pair_t, balance_t,
            additive<balance_pair_t, amount_t,
+           additive<balance_pair_t, double,
+           additive<balance_pair_t, unsigned long,
+           additive<balance_pair_t, long,
+           multiplicative<balance_pair_t, amount_t,
+           multiplicative<balance_pair_t, balance_t,
+           multiplicative<balance_pair_t, double,
            multiplicative<balance_pair_t, unsigned long,
-           multiplicative<balance_pair_t, long,
-	   multiplicative<balance_pair_t, amount_t> > > > > > > > >
+           multiplicative2<balance_pair_t, long, balance_t
+			   > > > > > > > > > > > > > > > > >
 {
-  balance_t	      quantity;
+  /**
+   * The `cost' member of a balance pair tracks the cost associated
+   * with each transaction amount that is added.  This member is
+   * optional, and if not cost-bearing transactions are added, it will
+   * remain uninitialized.
+   */
   optional<balance_t> cost;
 
+  /**
+   * The `quantity' method provides direct access to the balance_t
+   * base-class part of the balance pair.
+   */
+  balance_t& quantity() {
+    return *this;
+  }
+  const balance_t& quantity() const {
+    return *this;
+  }
+
   friend class value_t;
   friend class entry_base_t;
 
 public:
-  // constructors
+  /**
+   * Constructors.  balance_pair_t supports identical forms of construction
+   * to balance_t.  See balance_t for more information.
+   */
   balance_pair_t() {
     TRACE_CTOR(balance_pair_t, "");
   }
-  balance_pair_t(const balance_pair_t& bal_pair)
-    : quantity(bal_pair.quantity), cost(bal_pair.cost) {
-    TRACE_CTOR(balance_pair_t, "copy");
-  }
-  balance_pair_t(const balance_t& _quantity)
-    : quantity(_quantity) {
+  balance_pair_t(const balance_t& bal) : balance_t(bal) {
     TRACE_CTOR(balance_pair_t, "const balance_t&");
   }
-  balance_pair_t(const amount_t& _quantity)
-    : quantity(_quantity) {
+  balance_pair_t(const amount_t& amt) : balance_t(amt) {
     TRACE_CTOR(balance_pair_t, "const amount_t&");
   }
-  ~balance_pair_t() {
+  balance_pair_t(const double val) : balance_t(val) {
+    TRACE_CTOR(balance_pair_t, "const double");
+  }
+  balance_pair_t(const unsigned long val) : balance_t(val) {
+    TRACE_CTOR(balance_pair_t, "const unsigned long");
+  }
+  balance_pair_t(const long val) : balance_t(val) {
+    TRACE_CTOR(balance_pair_t, "const long");
+  }
+
+  explicit balance_pair_t(const string& val) : balance_t(val) {
+    TRACE_CTOR(balance_pair_t, "const string&");
+  }
+  explicit balance_pair_t(const char * val) : balance_t(val) {
+    TRACE_CTOR(balance_pair_t, "const char *");
+  }
+
+  /**
+   * Destructor.
+   */
+  virtual ~balance_pair_t() {
     TRACE_DTOR(balance_pair_t);
   }
 
-  // assignment operator
+  /**
+   * Assignment and copy operators.  A balance pair may be assigned or
+   * copied, and assigned or copied from a balance.
+   */
+  balance_pair_t(const balance_pair_t& bal_pair)
+    : balance_t(bal_pair), cost(bal_pair.cost) {
+    TRACE_CTOR(balance_pair_t, "copy");
+  }
+
   balance_pair_t& operator=(const balance_pair_t& bal_pair) {
     if (this != &bal_pair) {
-      quantity = bal_pair.quantity;
-      cost     = bal_pair.cost;
+      balance_t::operator=(bal_pair.quantity());
+      cost = bal_pair.cost;
     }
     return *this;
   }
+  balance_pair_t& operator=(const balance_t& bal) {
+    balance_t::operator=(bal);
+    return *this;
+  }
+  balance_pair_t& operator=(const amount_t& amt) {
+    balance_t::operator=(amt);
+    return *this;
+  }
+
+  balance_t& operator=(const string& str) {
+    return *this = balance_t(str);
+  }
+  balance_t& operator=(const char * str) {
+    return *this = balance_t(str);
+  }
 
   // in-place arithmetic
   balance_pair_t& operator+=(const balance_pair_t& bal_pair) {