balance.h

Go to the documentation of this file.

/*
 * Copyright (c) 2003-2025, John Wiegley.  All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are
 * met:
 *
 * - Redistributions of source code must retain the above copyright
 *   notice, this list of conditions and the following disclaimer.
 *
 * - Redistributions in binary form must reproduce the above copyright
 *   notice, this list of conditions and the following disclaimer in the
 *   documentation and/or other materials provided with the distribution.
 *
 * - Neither the name of New Artisans LLC nor the names of its
 *   contributors may be used to endorse or promote products derived from
 *   this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */


#pragma once
 
#include "amount.h"
 
namespace ledger {
 
DECLARE_EXCEPTION(balance_error, std::runtime_error);

class balance_t
  : public equality_comparable<balance_t,
           equality_comparable<balance_t, amount_t,
           equality_comparable<balance_t, double,
           equality_comparable<balance_t, unsigned long,
           equality_comparable<balance_t, long,
           additive<balance_t,
           additive<balance_t, amount_t,
           additive<balance_t, double,
           additive<balance_t, unsigned long,
           additive<balance_t, long,
           multiplicative<balance_t, amount_t,
           multiplicative<balance_t, double,
           multiplicative<balance_t, unsigned long,
           multiplicative<balance_t, long> > > > > > > > > > > > > >
{
public:
  typedef std::unordered_map<commodity_t *, amount_t> amounts_map;
  typedef std::vector<const amount_t *> amounts_array;
 
  amounts_map amounts;

  balance_t() {
    TRACE_CTOR(balance_t, "");
  }
  balance_t(const amount_t& amt) {
    if (amt.is_null())
      throw_(balance_error,
             _("Cannot initialize a balance from an uninitialized amount"));
    if (! amt.is_realzero())
      amounts.insert(amounts_map::value_type(&amt.commodity(), amt));
    TRACE_CTOR(balance_t, "const amount_t&");
  }
  balance_t(const double val);
  balance_t(const unsigned long val);
  balance_t(const long val);
 
  explicit balance_t(const string& val) {
    amount_t temp(val);
    amounts.insert(amounts_map::value_type(&temp.commodity(), temp));
    TRACE_CTOR(balance_t, "const string&");
  }
  explicit balance_t(const char * val) {
    amount_t temp(val);
    amounts.insert(amounts_map::value_type(&temp.commodity(), temp));
    TRACE_CTOR(balance_t, "const char *");
  }

  ~balance_t() {
    TRACE_DTOR(balance_t);
  }

  balance_t(const balance_t& bal) : amounts(bal.amounts) {
    TRACE_CTOR(balance_t, "copy");
  }
 
  balance_t& operator=(const balance_t& bal) {
    if (this != &bal)
      amounts = bal.amounts;
    return *this;
  }
  balance_t& operator=(const amount_t& amt) {
    if (amt.is_null())
      throw_(balance_error,
             _("Cannot assign an uninitialized amount to a balance"));
 
    amounts.clear();
    if (! amt.is_realzero())
      amounts.insert(amounts_map::value_type(&amt.commodity(), 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);
  }

  bool operator==(const balance_t& bal) const {
    return amounts == bal.amounts;
  }
  bool operator==(const amount_t& amt) const {
    if (amt.is_null())
      throw_(balance_error,
             _("Cannot compare a balance to an uninitialized amount"));
 
    if (amt.is_realzero())
      return amounts.empty();
    else
      return amounts.size() == 1 && amounts.begin()->second == amt;
  }
 
  template <typename T>
  bool operator==(const T& val) const {
    return *this == amount_t(val);
  }

  balance_t& operator+=(const balance_t& bal);
  balance_t& operator+=(const amount_t& amt);
  balance_t& operator+=(const double val) {
    return *this += amount_t(val);
  }
  balance_t& operator+=(const unsigned long val) {
    return *this += amount_t(val);
  }
  balance_t& operator+=(const long val) {
    return *this += amount_t(val);
  }
 
  balance_t& operator-=(const balance_t& bal);
  balance_t& operator-=(const amount_t& amt);
  balance_t& operator-=(const double val) {
    return *this -= amount_t(val);
  }
  balance_t& operator-=(const unsigned long val) {
    return *this -= amount_t(val);
  }
  balance_t& operator-=(const long val) {
    return *this -= amount_t(val);
  }
 
  balance_t& operator*=(const amount_t& amt);
  balance_t& operator*=(const double val) {
    return *this *= amount_t(val);
  }
  balance_t& operator*=(const unsigned long val) {
    return *this *= amount_t(val);
  }
  balance_t& operator*=(const long val) {
    return *this *= amount_t(val);
  }
 
  balance_t& operator/=(const amount_t& amt);
  balance_t& operator/=(const double val) {
    return *this /= amount_t(val);
  }
  balance_t& operator/=(const unsigned long val) {
    return *this /= amount_t(val);
  }
  balance_t& operator/=(const long val) {
    return *this /= amount_t(val);
  }

  balance_t negated() const {
    balance_t temp(*this);
    temp.in_place_negate();
    return temp;
  }
  void in_place_negate() {
    foreach (amounts_map::value_type& pair, amounts)
      pair.second.in_place_negate();
  }
  balance_t operator-() const {
    return negated();
  }
 
  balance_t abs() const {
    balance_t temp;
    foreach (const amounts_map::value_type& pair, amounts)
      temp += pair.second.abs();
    return temp;
  }
 
  balance_t rounded() const {
    balance_t temp(*this);
    temp.in_place_round();
    return temp;
  }
  void in_place_round() {
    foreach (amounts_map::value_type& pair, amounts)
      pair.second.in_place_round();
  }
 
  balance_t roundto(int places) const {
    balance_t temp(*this);
    temp.in_place_roundto(places);
    return temp;
  }
 
  void in_place_roundto(int places) {
    foreach (amounts_map::value_type& pair, amounts)
      pair.second.in_place_roundto(places);
  }
 
  balance_t truncated() const {
    balance_t temp(*this);
    temp.in_place_truncate();
    return temp;
  }
  void in_place_truncate() {
    foreach (amounts_map::value_type& pair, amounts)
      pair.second.in_place_truncate();
  }
 
  balance_t floored() const {
    balance_t temp(*this);
    temp.in_place_floor();
    return temp;
  }
  void in_place_floor() {
    foreach (amounts_map::value_type& pair, amounts)
      pair.second.in_place_floor();
  }
 
  balance_t ceilinged() const {
    balance_t temp(*this);
    temp.in_place_ceiling();
    return temp;
  }
  void in_place_ceiling() {
    foreach (amounts_map::value_type& pair, amounts)
      pair.second.in_place_ceiling();
  }
 
 
  balance_t unrounded() const {
    balance_t temp(*this);
    temp.in_place_unround();
    return temp;
  }
  void in_place_unround() {
    foreach (amounts_map::value_type& pair, amounts)
      pair.second.in_place_unround();
  }
 
  balance_t reduced() const {
    balance_t temp(*this);
    temp.in_place_reduce();
    return temp;
  }
  void in_place_reduce() {
    // A temporary must be used here because reduction may cause
    // multiple component amounts to collapse to the same commodity.
    balance_t temp;
    foreach (const amounts_map::value_type& pair, amounts)
      temp += pair.second.reduced();
    *this = temp;
  }
 
  balance_t unreduced() const {
    balance_t temp(*this);
    temp.in_place_unreduce();
    return temp;
  }
  void in_place_unreduce() {
    // A temporary must be used here because unreduction may cause
    // multiple component amounts to collapse to the same commodity.
    balance_t temp;
    foreach (const amounts_map::value_type& pair, amounts)
      temp += pair.second.unreduced();
    *this = temp;
  }
 
  optional<balance_t>
  value(const datetime_t&   moment      = datetime_t(),
        const commodity_t * in_terms_of = NULL) const;

  operator bool() const {
    return is_nonzero();
  }
 
  bool is_nonzero() const {
    if (is_empty())
      return false;
 
    foreach (const amounts_map::value_type& pair, amounts)
      if (pair.second.is_nonzero())
        return true;
    return false;
  }
 
  bool is_zero() const {
    if (is_empty())
      return true;
 
    foreach (const amounts_map::value_type& pair, amounts)
      if (! pair.second.is_zero())
        return false;
    return true;
  }
 
  bool is_realzero() const {
    if (is_empty())
      return true;
 
    foreach (const amounts_map::value_type& pair, amounts)
      if (! pair.second.is_realzero())
        return false;
    return true;
  }
 
  bool is_empty() const {
    return amounts.size() == 0;
  }
  bool single_amount() const {
    return amounts.size() == 1;
  }

  operator string() const {
    return to_string();
  }
  string to_string() const {
    std::ostringstream buf;
    print(buf);
    return buf.str();
  }
 
  amount_t to_amount() const {
    if (is_empty())
      throw_(balance_error, _("Cannot convert an empty balance to an amount"));
    else if (amounts.size() == 1)
      return amounts.begin()->second;
    else
      throw_(balance_error,
             _("Cannot convert a balance with multiple commodities to an amount"));
    return amount_t();
  }

  std::size_t commodity_count() const {
    return amounts.size();
  }
 
  optional<amount_t>
  commodity_amount(const optional<const commodity_t&>& commodity = none) const;
 
  amounts_map::iterator find_by_name(const commodity_t& comm);
  amounts_map::const_iterator find_by_name(const commodity_t& comm) const;
 
  balance_t number() const {
    balance_t temp;
    foreach (const amounts_map::value_type& pair, amounts)
      temp += pair.second.number();
    return temp;
  }

  balance_t strip_annotations(const keep_details_t& what_to_keep) const;

  void sorted_amounts(amounts_array& sorted) const;

  void map_sorted_amounts(function<void(const amount_t&)> fn) const;

  void print(std::ostream&       out,
             const int           first_width  = -1,
             const int           latter_width = -1,
             const uint_least8_t flags        = AMOUNT_PRINT_NO_FLAGS) const;

  void dump(std::ostream& out) const {
    out << "BALANCE(";
    bool first = true;
    foreach (const amounts_map::value_type& pair, amounts) {
      if (first)
        first = false;
      else
        out << ", ";
      pair.second.print(out);
    }
    out << ")";
  }
 
  bool valid() const {
    foreach (const amounts_map::value_type& pair, amounts)
      if (! pair.second.valid()) {
        DEBUG("ledger.validate", "balance_t: ! pair.second.valid()");
        return false;
      }
    return true;
  }
};
 
inline std::ostream& operator<<(std::ostream& out, const balance_t& bal) {
  bal.print(out, 12);
  return out;
}
 
void put_balance(property_tree::ptree& pt, const balance_t& bal);
 
balance_t average_lot_prices(const balance_t& bal);
 
} // namespace ledger