[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[taler-taler-util] 01/07: touch up ‘Amount’, ‘SignedAmount’ section
From: |
gnunet |
Subject: |
[taler-taler-util] 01/07: touch up ‘Amount’, ‘SignedAmount’ section |
Date: |
Fri, 11 Feb 2022 01:45:23 +0100 |
This is an automated email from the git hooks/post-receive script.
ttn pushed a commit to branch master
in repository taler-util.
commit f50b0e31a474d60be49486f7524a1b182f9c129e
Author: Thien-Thi Nguyen <ttn@gnuvola.org>
AuthorDate: Thu Feb 10 18:17:15 2022 -0500
touch up ‘Amount’, ‘SignedAmount’ section
- use new section heading
- rework first para
- move format to example block
- mention aka ‘CUR:X.Y’
- revamp "import" line, plus references
---
doc/doc.org | 24 +++++++++++++++---------
1 file changed, 15 insertions(+), 9 deletions(-)
diff --git a/doc/doc.org b/doc/doc.org
index e0905db..b1be861 100644
--- a/doc/doc.org
+++ b/doc/doc.org
@@ -47,11 +47,17 @@ The rest are /leaf classes/.
- SectionDict(collections.defaultdict)
- TalerConfig
-* classes =Amount=, =SignedAmount=
+* classes for handling currency plus value plus fraction
-These classes handle Taler /amounts/, objects referred to in the format
-=CURRENCY:VALUE.FRACTION=, where =CURRENCY= is the currency designation
-abbreviation (e.g., "KUDOS"), and =VALUE= and =FRACTION= are integers.
+The =Amount= and =SignedAmount= handle Taler /amounts/,
+objects that combine a =CURRENCY= (e.g., "KUDOS")
+with a =VALUE= and =FRACTION= (both integers).
+An amount is written as follows:
+
+: CURRENCY:VALUE.FRACTION
+
+Note the =:= (colon) and =.= (period).
+This is also known as the =CUR:X.Y= format.
The maximum =VALUE= is 2^52 (i.e., 4503599627370496).
The =FRACTION= can be at most 8 digits (i.e., smallest non-zero
@@ -64,9 +70,9 @@ the constructor throws an =AmountOverflowError= exception.
The constructor takes three args: /currency/, /value/, /fraction/.
-: >>> from taler.util import amount
+: >>> from taler.util.amount import Amount, SignedAmount
: # KUDOS 10.50
-: >>> amt = amount.Amount ("KUDOS", 10, 50000000)
+: >>> amt = Amount ("KUDOS", 10, 50000000)
: >>> amt
: Amount(currency='KUDOS', value=10, fraction=50000000)
@@ -79,7 +85,7 @@ You can use classmethod =parse= to read a string as an
=Amount= object.
This function can throw =AmountFormatError= if the string is malformed,
and =AmountOverflowError= if the fraction portion is too long.
-: >>> amount.Amount.parse ("KUDOS:10.12345678")
+: >>> Amount.parse ("KUDOS:10.12345678")
: Amount(currency='KUDOS', value=10, fraction=12345678)
An =Amount= object supports addition and subtraction.
@@ -88,7 +94,7 @@ a =CurrencyMismatchError= exception.
: >>> amt + amt
: Amount(currency='KUDOS', value=21, fraction=0)
-: >>> another = amount.Amount ("KUDOS", 5, 42)
+: >>> another = Amount ("KUDOS", 5, 42)
: >>> amt - another
: Amount(currency='KUDOS', value=5, fraction=49999958)
@@ -165,7 +171,7 @@ The classmethod =parse= recognizes a leading =+= or =-=, and
additionally accepts a plain =CURRENCY:VALUE.FRACTION= form as a
positive =SignedAmount=.
-: >>> amount.SignedAmount.parse ("-KUDOS:2.34")
+: >>> SignedAmount.parse ("-KUDOS:2.34")
: SignedAmount(is_positive=False, amount=Amount(currency='KUDOS', value=2,
fraction=34000000))
Lastly, a =SignedAmount= object can flip its sign using a unary minus.
--
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.
- [taler-taler-util] branch master updated (35bc3d7 -> 262b998), gnunet, 2022/02/10
- [taler-taler-util] 02/07: change markup for Amount ctor args, properties from / to =, gnunet, 2022/02/10
- [taler-taler-util] 04/07: include "+ fraction" in subheading, gnunet, 2022/02/10
- [taler-taler-util] 03/07: touch up ‘GnunetLogger’ section, gnunet, 2022/02/10
- [taler-taler-util] 01/07: touch up ‘Amount’, ‘SignedAmount’ section,
gnunet <=
- [taler-taler-util] 05/07: add vertical space to example blocks, gnunet, 2022/02/10
- [taler-taler-util] 06/07: add documentation for payto.py, gnunet, 2022/02/10
- [taler-taler-util] 07/07: regenerate doc.{html,txt}, gnunet, 2022/02/10