From e6663212fff323d2750fdc6cf754da860cad1533 Mon Sep 17 00:00:00 2001 From: Jack Grigg Date: Thu, 8 Aug 2019 09:21:09 +0100 Subject: [PATCH] Improve documentation for Amount --- .../src/transaction/components/amount.rs | 27 +++++++++++++------ 1 file changed, 19 insertions(+), 8 deletions(-) diff --git a/zcash_primitives/src/transaction/components/amount.rs b/zcash_primitives/src/transaction/components/amount.rs index d244876b2..f2d9d0fd1 100644 --- a/zcash_primitives/src/transaction/components/amount.rs +++ b/zcash_primitives/src/transaction/components/amount.rs @@ -6,6 +6,17 @@ const MAX_MONEY: i64 = 21_000_000 * COIN; pub const DEFAULT_FEE: Amount = Amount(10000); +/// A type-safe representation of some quantity of Zcash. +/// +/// An Amount can only be constructed from an integer that is within the valid monetary +/// range of `{-MAX_MONEY..MAX_MONEY}` (where `MAX_MONEY` = 21,000,000 × 10⁸ zatoshis). +/// However, this range is not preserved as an invariant internally; it is possible to +/// add two valid Amounts together to obtain an invalid Amount. It is the user's +/// responsibility to handle the result of serializing potentially-invalid Amounts. In +/// particular, a [`Transaction`] containing serialized invalid Amounts will be rejected +/// by the network consensus rules. +/// +/// [`Transaction`]: crate::transaction::Transaction #[derive(Clone, Copy, Debug, PartialEq)] pub struct Amount(i64); @@ -17,7 +28,7 @@ impl Amount { /// Creates an Amount from an i64. /// - /// Returns an error if the amount is out of range. + /// Returns an error if the amount is outside the range `{-MAX_MONEY..MAX_MONEY}`. pub fn from_i64(amount: i64) -> Result { if -MAX_MONEY <= amount && amount <= MAX_MONEY { Ok(Amount(amount)) @@ -28,7 +39,7 @@ impl Amount { /// Creates a non-negative Amount from an i64. /// - /// Returns an error if the amount is out of range. + /// Returns an error if the amount is outside the range `{0..MAX_MONEY}`. pub fn from_nonnegative_i64(amount: i64) -> Result { if 0 <= amount && amount <= MAX_MONEY { Ok(Amount(amount)) @@ -39,7 +50,7 @@ impl Amount { /// Creates an Amount from a u64. /// - /// Returns an error if the amount is out of range. + /// Returns an error if the amount is outside the range `{0..MAX_MONEY}`. pub fn from_u64(amount: u64) -> Result { if amount <= MAX_MONEY as u64 { Ok(Amount(amount as i64)) @@ -50,7 +61,7 @@ impl Amount { /// Reads an Amount from a signed 64-bit little-endian integer. /// - /// Returns an error if the amount is out of range. + /// Returns an error if the amount is outside the range `{-MAX_MONEY..MAX_MONEY}`. pub fn from_i64_le_bytes(bytes: [u8; 8]) -> Result { let amount = i64::from_le_bytes(bytes); Amount::from_i64(amount) @@ -58,7 +69,7 @@ impl Amount { /// Reads a non-negative Amount from a signed 64-bit little-endian integer. /// - /// Returns an error if the amount is out of range. + /// Returns an error if the amount is outside the range `{0..MAX_MONEY}`. pub fn from_nonnegative_i64_le_bytes(bytes: [u8; 8]) -> Result { let amount = i64::from_le_bytes(bytes); Amount::from_nonnegative_i64(amount) @@ -66,7 +77,7 @@ impl Amount { /// Reads an Amount from an unsigned 64-bit little-endian integer. /// - /// Returns an error if the amount is out of range. + /// Returns an error if the amount is outside the range `{0..MAX_MONEY}`. pub fn from_u64_le_bytes(bytes: [u8; 8]) -> Result { let amount = u64::from_le_bytes(bytes); Amount::from_u64(amount) @@ -77,13 +88,13 @@ impl Amount { self.0.to_le_bytes() } - /// Returns `true` if `self` is positive and `false` if the number is zero or + /// Returns `true` if `self` is positive and `false` if the Amount is zero or /// negative. pub const fn is_positive(self) -> bool { self.0.is_positive() } - /// Returns `true` if `self` is negative and `false` if the number is zero or + /// Returns `true` if `self` is negative and `false` if the Amount is zero or /// positive. pub const fn is_negative(self) -> bool { self.0.is_negative()