Encapsulate infinite-precision commoditized amounts. More...
#include <amount.h>
Inherits ordered_field_operators< amount_t, ordered_field_operators< amount_t, double, ordered_field_operators< amount_t, unsigned long, ordered_field_operators< amount_t, long > > > >.
Public Types | |
typedef uint_least16_t | precision_t |
The amount's decimal precision. | |
Public Member Functions | |
Assignment and copy | |
amount_t (const amount_t &amt) | |
Copy an amount object. | |
amount_t (const amount_t &amt, const annotation_t &details) | |
Copy an amount object, applying the given commodity annotation details afterward. | |
amount_t & | operator= (const amount_t &amt) |
Assign an amount object. | |
amount_t & | operator= (const double val) |
amount_t & | operator= (const unsigned long val) |
amount_t & | operator= (const long val) |
amount_t & | operator= (const string &str) |
amount_t & | operator= (const char *str) |
Comparison | |
int | compare (const amount_t &amt) const |
Compare two amounts, returning a number less than zero if amt is greater, exactly zero if they are equal, and greater than zero if amt is less. | |
bool | operator== (const amount_t &amt) const |
Test two amounts for equality. | |
template<typename T > | |
bool | operator== (const T &val) const |
template<typename T > | |
bool | operator< (const T &amt) const |
template<typename T > | |
bool | operator> (const T &amt) const |
Binary arithmetic | |
amount_t & | operator+= (const amount_t &amt) |
amount_t & | operator-= (const amount_t &amt) |
amount_t & | operator*= (const amount_t &amt) |
amount_t & | multiply (const amount_t &amt, bool ignore_commodity=false) |
amount_t & | operator/= (const amount_t &amt) |
Divide two amounts while extending the precision to preserve the accuracy of the result. | |
Unary arithmetic | |
precision_t | precision () const |
Return an amount's internal precision. | |
bool | keep_precision () const |
void | set_keep_precision (const bool keep=true) const |
precision_t | display_precision () const |
amount_t | negated () const |
Returns the negated value of an amount. | |
void | in_place_negate () |
amount_t | operator- () const |
amount_t | abs () const |
Returns the absolute value of an amount. | |
amount_t | inverted () const |
void | in_place_invert () |
amount_t | rounded () const |
Yields an amount whose display precision when output is truncated to the display precision of its commodity. | |
void | in_place_round () |
amount_t | roundto (int places) const |
void | in_place_roundto (int places) |
amount_t | truncated () const |
Yields an amount which has lost all of its extra precision, beyond what the display precision of the commodity would have printed. | |
void | in_place_truncate () |
amount_t | floored () const |
Yields an amount which has lost all of its extra precision, beyond what the display precision of the commodity would have printed. | |
void | in_place_floor () |
amount_t | ceilinged () const |
Yields an amount which has lost all of its extra precision, beyond what the display precision of the commodity would have printed. | |
void | in_place_ceiling () |
amount_t | unrounded () const |
Yields an amount whose display precision is never truncated, even though its commodity normally displays only rounded values. | |
void | in_place_unround () |
amount_t | reduced () const |
reduces a value to its most basic commodity form, for amounts that utilize "scaling commodities". | |
void | in_place_reduce () |
amount_t | unreduced () const |
unreduce(), if used with a "scaling commodity", yields the most compact form greater than one. | |
void | in_place_unreduce () |
optional< amount_t > | value (const datetime_t &moment=datetime_t(), const commodity_t *in_terms_of=NULL) const |
Returns the historical value for an amount – the default moment returns the most recently known price – based on the price history for the given commodity (or determined automatically, if none is provided). | |
optional< amount_t > | price () const |
Truth tests | |
int | sign () const |
Truth tests. | |
operator bool () const | |
bool | is_nonzero () const |
bool | is_zero () const |
bool | is_realzero () const |
bool | is_null () const |
Conversion | |
double | to_double () const |
Conversion methods. | |
long | to_long () const |
bool | fits_in_long () const |
operator string () const | |
string | to_string () const |
string | to_fullstring () const |
string | quantity_string () const |
Commodity methods | |
commodity_t * | commodity_ptr () const |
The following methods relate to an amount's commodity: | |
commodity_t & | commodity () const |
bool | has_commodity () const |
void | set_commodity (commodity_t &comm) |
amount_t | with_commodity (const commodity_t &comm) const |
void | clear_commodity () |
amount_t | number () const |
Commodity annotations | |
void | annotate (const annotation_t &details) |
An amount's commodity may be annotated with special details, such as the price it was purchased for, when it was acquired, or an arbitrary note, identifying perhaps the lot number of an item. | |
bool | has_annotation () const |
annotation_t & | annotation () |
const annotation_t & | annotation () const |
amount_t | strip_annotations (const keep_details_t &what_to_keep) const |
If the lot price is considered whenever working with commoditized values. | |
Printing | |
void | print (std::ostream &out, const uint_least8_t flags=0x00) const |
Debugging | |
void | dump (std::ostream &out) const |
There are two methods defined to help with debugging: | |
bool | valid () const |
Static Public Member Functions | |
static void | initialize () |
Ready the amount subsystem for use. | |
static void | shutdown () |
Shutdown the amount subsystem and free all resources. | |
Static Public Attributes | |
static const std::size_t | extend_by_digits = 6U |
Number of places of precision by which values are extended to avoid losing precision during division and multiplication. | |
static bool | is_initialized |
static bool | stream_fullstrings |
If amounts should be streamed using to_fullstring() rather than to_string(), so that complete precision is always displayed no matter what the precision of an individual commodity may be. | |
Protected Member Functions | |
void | _clear () |
void | _copy (const amount_t &amt) |
void | _dup () |
void | _release () |
Protected Attributes | |
commodity_t * | commodity_ |
bigint_t * | quantity |
Constructors | |
static amount_t | exact (const string &value) |
Create an amount whose display precision is never truncated, even if the amount uses a commodity (which normally causes "round on
streaming" to occur). | |
amount_t () | |
Creates a value for which is_null() is true, and which has no value or commodity. | |
amount_t (const double val) | |
Convert a double to an amount. | |
amount_t (const unsigned long val) | |
Convert an unsigned long to an amount. | |
amount_t (const long val) | |
Convert a long to an amount. | |
amount_t (const string &val) | |
Parse a string as an (optionally commoditized) amount. | |
amount_t (const char *val) | |
Parse a pointer to a C string as an (optionally commoditized) amount. | |
~amount_t () | |
Release the reference count held for the underlying amount_t::bigint_t object. | |
Parsing | |
static void | parse_conversion (const string &larger_str, const string &smaller_str) |
bool | parse (std::istream &in, const parse_flags_t &flags=PARSE_DEFAULT) |
The ‘flags’ argument of both parsing may be one or more of the following: | |
bool | parse (const string &str, const parse_flags_t &flags=PARSE_DEFAULT) |
Encapsulate infinite-precision commoditized amounts.
Used to represent commoditized infinite-precision numbers, and uncommoditized, plain numbers. In the commoditized case, commodities keep track of how they are used, and are always displayed back to the user after the same fashion. For uncommoditized numbers, no display truncation is ever done. In both cases, internal precision is always kept to an excessive degree.
|
inline |
Creates a value for which is_null() is true, and which has no value or commodity.
If used in a value expression it evaluates to zero, and its commodity equals commodity_t::null_commodity
.
Definition at line 137 of file amount.h.
References TRACE_CTOR.
Referenced by operator=(), operator=(), operator=(), operator=(), and operator=().
Convert a double to an amount.
As much precision as possible is decoded from the binary floating point number.
Convert an unsigned long to an amount.
It's precision is zero.
Convert a long to an amount.
It's precision is zero, and the sign is preserved.
Parse a string as an (optionally commoditized) amount.
If no commodity is present, the resulting commodity is commodity_t::null_commodity
. The number may be of infinite precision.
Definition at line 156 of file amount.h.
References parse(), and TRACE_CTOR.
Parse a pointer to a C string as an (optionally commoditized) amount.
If no commodity is present, the resulting commodity is commodity_t::null_commodity
. The number may be of infinite precision.
Definition at line 164 of file amount.h.
References assert, parse(), and TRACE_CTOR.
|
inline |
Release the reference count held for the underlying amount_t::bigint_t
object.
Definition at line 183 of file amount.h.
References _release(), quantity, and TRACE_DTOR.
Copy an amount object.
Copies are very efficient, using a copy-on-write model. Until the copy is changed, it refers to the same memory used by the original via reference counting. The amount_t::bigint_t
class in amount.cc maintains the reference.
Definition at line 196 of file amount.h.
References _copy(), commodity_, quantity, and TRACE_CTOR.
|
inline |
Copy an amount object, applying the given commodity annotation details afterward.
This is equivalent to doing a normal copy (
Definition at line 207 of file amount.h.
References _copy(), annotate(), assert, quantity, and TRACE_CTOR.
|
protected |
|
protected |
|
protected |
|
inline |
void ledger::amount_t::annotate | ( | const annotation_t & | details | ) |
An amount's commodity may be annotated with special details, such as the price it was purchased for, when it was acquired, or an arbitrary note, identifying perhaps the lot number of an item.
annotate_commodity(amount_t price, [datetime_t date, string tag]) sets the annotations for the current amount's commodity. Only the price argument is required, although it can be passed as ‘none’ if no price is desired.
commodity_annotated() returns true if an amount's commodity has any annotation details associated with it.
annotation_details() returns all of the details of an annotated commodity's annotations. The structure returns will evaluate as boolean false if there are no details.
strip_annotations() returns an amount whose commodity's annotations have been stripped.
Referenced by amount_t().
annotation_t & ledger::amount_t::annotation | ( | ) |
|
inline |
Definition at line 613 of file amount.h.
References annotation().
|
inline |
Yields an amount which has lost all of its extra precision, beyond what the display precision of the commodity would have printed.
Definition at line 375 of file amount.h.
References in_place_ceiling().
|
inline |
Definition at line 571 of file amount.h.
References commodity_.
Referenced by number().
|
inline |
Definition at line 552 of file amount.h.
References commodity_ptr().
commodity_t * ledger::amount_t::commodity_ptr | ( | ) | const |
The following methods relate to an amount's commodity:
commodity() returns an amount's commodity. If the amount has no commodity, the value returned is the ‘null_commodity’.
has_commodity() returns true if the amount has a commodity.
set_commodity(commodity_t) sets an amount's commodity to the given value. Note that this merely sets the current amount to that commodity, it does not "observe" the amount for possible changes in the maximum display precision of the commodity, the way that ‘parse’ does.
clear_commodity() sets an amount's commodity to null, such that has_commodity() afterwards returns false.
number() returns a commodity-less version of an amount. This is useful for accessing just the numeric portion of an amount.
Referenced by commodity().
Compare two amounts, returning a number less than zero if amt
is greater, exactly zero if they are equal, and greater than zero if amt
is less.
This method is used to implement all of the other comparison methods.
Referenced by operator<(), operator==(), and operator>().
precision_t ledger::amount_t::display_precision | ( | ) | const |
|
inline |
There are two methods defined to help with debugging:
dump(ostream) dumps an amount to an output stream. There is little different from print(), it simply surrounds the display value with a marker, for example "AMOUNT($1.00)". This code is used by other dumping code elsewhere in Ledger.
valid() returns true if an amount is valid. This ensures that if an amount has a commodity, it has a valid value pointer, for example, even if that pointer simply points to a zero value.
Definition at line 737 of file amount.h.
References print().
Create an amount whose display precision is never truncated, even if the amount uses a commodity (which normally causes "round on streaming" to occur).
This function is mostly used by debugging code and unit tests. This is the proper way to specify $100
.005, where display of the extra digit precision is required. If a regular constructor were used, the amount would stream as $100
.01, even though its internal value equals $100
.005.
Definition at line 748 of file amount.h.
References parse(), ledger::PARSE_NO_MIGRATE, and value().
bool ledger::amount_t::fits_in_long | ( | ) | const |
|
inline |
Yields an amount which has lost all of its extra precision, beyond what the display precision of the commodity would have printed.
Definition at line 366 of file amount.h.
References in_place_floor().
bool ledger::amount_t::has_annotation | ( | ) | const |
bool ledger::amount_t::has_commodity | ( | ) | const |
void ledger::amount_t::in_place_ceiling | ( | ) |
void ledger::amount_t::in_place_floor | ( | ) |
void ledger::amount_t::in_place_invert | ( | ) |
void ledger::amount_t::in_place_negate | ( | ) |
void ledger::amount_t::in_place_reduce | ( | ) |
void ledger::amount_t::in_place_round | ( | ) |
void ledger::amount_t::in_place_truncate | ( | ) |
void ledger::amount_t::in_place_unreduce | ( | ) |
void ledger::amount_t::in_place_unround | ( | ) |
Ready the amount subsystem for use.
|
inline |
Definition at line 329 of file amount.h.
References in_place_invert().
|
inline |
Definition at line 461 of file amount.h.
References is_zero().
Referenced by operator bool().
|
inline |
Definition at line 470 of file amount.h.
References assert, commodity_, and quantity.
|
inline |
bool ledger::amount_t::is_zero | ( | ) | const |
bool ledger::amount_t::keep_precision | ( | ) | const |
|
inline |
Returns the negated value of an amount.
Definition at line 307 of file amount.h.
References in_place_negate().
Referenced by abs(), and operator-().
|
inline |
Definition at line 575 of file amount.h.
References clear_commodity(), and has_commodity().
Referenced by quantity_string().
|
inline |
Definition at line 458 of file amount.h.
References is_nonzero().
|
inline |
Definition at line 518 of file amount.h.
References to_string().
Definition at line 276 of file amount.h.
References multiply().
|
inline |
Divide two amounts while extending the precision to preserve the accuracy of the result.
For example, if 10
is divided by 3
, the result ends up having a precision of amount_t::extend_by_digits place to avoid losing internal resolution.
Assign an amount object.
This is like copying if the amount was null beforehand, otherwise the previous value's reference is must be freed.
Definition at line 234 of file amount.h.
References amount_t(), and assert.
Definition at line 218 of file amount.h.
References amount_t().
Definition at line 224 of file amount.h.
References amount_t().
Definition at line 231 of file amount.h.
References amount_t().
Definition at line 221 of file amount.h.
References amount_t().
Test two amounts for equality.
First the commodity pointers are quickly tested, then the multi-precision values themselves must be compared.
|
inline |
bool ledger::amount_t::parse | ( | std::istream & | in, |
const parse_flags_t & | flags = PARSE_DEFAULT ) |
The ‘flags’ argument of both parsing may be one or more of the following:
PARSE_NO_MIGRATE means to not pay attention to the way an amount is used. Ordinarily, if an amount were $100.001, for example, it would cause the default display precision for $ to be "widened" to three decimal places. If PARSE_NO_MIGRATE is used, the commodity's default display precision is not changed.
PARSE_NO_REDUCE means not to call in_place_reduce() on the resulting amount after it is parsed.
These parsing methods observe the amounts they parse (unless PARSE_NO_MIGRATE is true), and set the display details of the corresponding commodity accordingly. This way, amounts do not require commodities to be pre-defined in any way, but merely displays them back to the user in the same fashion as it saw them used.
There is also a static convenience method called ‘parse_conversion’ which can be used to define a relationship between scaling commodity values. For example, Ledger uses it to define the relationships among various time values:
The method parse() is used to parse an amount from an input stream or a string. A global operator>>() is also defined which simply calls parse on the input stream. The parse() method has two forms:
parse(istream, flags_t) parses an amount from the given input stream.
parse(string, flags_t) parses an amount from the given string.
parse(string, flags_t) also parses an amount from a string.
Referenced by amount_t(), amount_t(), exact(), ledger::operator>>(), and parse().
|
static |
precision_t ledger::amount_t::precision | ( | ) | const |
Return an amount's internal precision.
To find the precision it should be displayed at – assuming it was not created using amount_t::exact() – use the following expression instead:
void ledger::amount_t::print | ( | std::ostream & | out, |
const uint_least8_t | flags = 0x00 ) const |
Referenced by dump(), ledger::operator<<(), quantity_string(), to_fullstring(), and to_string().
|
inline |
|
inline |
reduces a value to its most basic commodity form, for amounts that utilize "scaling commodities".
For example, an amount of 1h
after reduction will be 3600s
.
Definition at line 395 of file amount.h.
References in_place_reduce().
|
inline |
Yields an amount whose display precision when output is truncated to the display precision of its commodity.
This is normally the default state of an amount, but if one has become unrounded, this sets the "keep precision" state back to false.
Definition at line 341 of file amount.h.
References in_place_round().
Definition at line 348 of file amount.h.
References in_place_roundto().
|
inline |
Definition at line 557 of file amount.h.
References commodity_, and quantity.
Referenced by with_commodity().
Shutdown the amount subsystem and free all resources.
int ledger::amount_t::sign | ( | ) | const |
Truth tests.
An amount may be truth test in several ways:
sign() returns an integer less than, greater than, or equal to zero depending on whether the amount is negative, zero, or greater than zero. Note that this function tests the actual value of the amount – using its internal precision – and not the display value. To test its display value, use: ‘round().sign()’.
is_nonzero(), or operator bool, returns true if an amount's display value is not zero.
is_zero() returns true if an amount's display value is zero. Thus, $0.0001 is considered zero if the current display precision for dollars is two decimal places.
is_realzero() returns true if an amount's actual value is zero. Thus, $0.0001 is never considered realzero.
is_null() returns true if an amount has no value and no commodity. This only occurs if an uninitialized amount has never been assigned a value.
Referenced by abs(), and is_realzero().
amount_t ledger::amount_t::strip_annotations | ( | const keep_details_t & | what_to_keep | ) | const |
If the lot price is considered whenever working with commoditized values.
Let's say a user adds two values of the following form:
This expression adds ten shares of Apple stock with another ten shares that were purchased for $20
a share. If keep_price
is false, the result of this expression is an amount equal to 20 AAPL
. If keep_price
is true
the expression yields an exception for adding amounts with different commodities. In that case, a balance_t object must be used to store the combined sum.
double ledger::amount_t::to_double | ( | ) | const |
Conversion methods.
An amount may be converted to the same types it can be constructed from – with the exception of unsigned long. Implicit conversions are not allowed in C++ (though they are in Python), rather the following conversion methods must be called explicitly:
to_double([bool]) returns an amount as a double. If the optional boolean argument is true (the default), an exception is thrown if the conversion would lose information.
to_long([bool]) returns an amount as a long integer. If the optional boolean argument is true (the default), an exception is thrown if the conversion would lose information.
fits_in_long() returns true if to_long() would not lose precision.
to_string() returns an amount's "display value" as a string – after rounding the value according to the commodity's default precision. It is equivalent to: ‘round().to_fullstring()’.
to_fullstring() returns an amount's "internal value" as a string, without any rounding.
quantity_string() returns an amount's "display value", but without any commodity. Note that this is different from ‘number().to_string()’, because in that case the commodity has been stripped and the full, internal precision of the amount would be displayed.
|
inline |
Definition at line 760 of file amount.h.
References print(), and unrounded().
long ledger::amount_t::to_long | ( | ) | const |
|
inline |
Definition at line 754 of file amount.h.
References print().
Referenced by operator string().
|
inline |
Yields an amount which has lost all of its extra precision, beyond what the display precision of the commodity would have printed.
Definition at line 357 of file amount.h.
References in_place_truncate().
|
inline |
unreduce(), if used with a "scaling commodity", yields the most compact form greater than one.
That is, 3599s
will unreduce to 59.98m
, while 3601
unreduces to 1h
.
Definition at line 406 of file amount.h.
References in_place_unreduce().
|
inline |
Yields an amount whose display precision is never truncated, even though its commodity normally displays only rounded values.
Definition at line 384 of file amount.h.
References in_place_unround().
Referenced by ledger::operator<<(), and to_fullstring().
bool ledger::amount_t::valid | ( | ) | const |
optional< amount_t > ledger::amount_t::value | ( | const datetime_t & | moment = datetime_t(), |
const commodity_t * | in_terms_of = NULL ) const |
Returns the historical value for an amount – the default moment returns the most recently known price – based on the price history for the given commodity (or determined automatically, if none is provided).
For example, if the amount were 10 AAPL
, and on Apr 10, 2000 each share of AAPL
was worth $10
, then calling value() for that moment in time would yield the amount $100
.00.
Referenced by exact().
|
inline |
Definition at line 562 of file amount.h.
References commodity_, and set_commodity().
|
protected |
Definition at line 128 of file amount.h.
Referenced by amount_t(), clear_commodity(), is_null(), set_commodity(), and with_commodity().
|
protected |
Definition at line 127 of file amount.h.
Referenced by amount_t(), amount_t(), is_null(), set_commodity(), and ~amount_t().
|
static |
If amounts should be streamed using to_fullstring() rather than to_string(), so that complete precision is always displayed no matter what the precision of an individual commodity may be.
Definition at line 117 of file amount.h.
Referenced by ledger::operator<<().