milksad
/
rust-bitcoin-unsafe-fast
14
0
Fork 0
Code Issues Pull Requests Activity

Fix rustdoc grammar 

In the rustdocs, made all function descriptions third person. Corrected
some grammar and improved some wording.
This commit is contained in:
Jamil Lambert, PhD 2024-07-03 15:09:02 +01:00
parent 573f8ce724
commit 75f317a689
7 changed files with 76 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

62
units/src/amount.rs
View File

@ -67,7 +67,7 @@ impl Denomination {
}
}
/// Returns stringly representation of this
/// Returns a string representation of this denomination.
fn as_str(self) -> &'static str {
match self {
Denomination::Bitcoin => "BTC",
@ -105,7 +105,7 @@ impl fmt::Display for Denomination {
impl FromStr for Denomination {
type Err = ParseDenominationError;
/// Convert from a `str` to `Denomination`.
/// Converts from a `str` to a `Denomination`.
///
/// # Accepted Denominations
///
@ -260,7 +260,7 @@ impl std::error::Error for ParseAmountError {
}
}
/// Returned when a parsed amount is too big or too small.
/// Error returned when a parsed amount is too big or too small.
#[derive(Debug, Copy, Clone, Eq, PartialEq)]
pub struct OutOfRangeError {
is_signed: bool,
@ -395,7 +395,7 @@ enum MissingDigitsKind {
OnlyMinusSign,
}
/// Returned when the input contains an invalid character.
/// Error returned when the input contains an invalid character.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct InvalidCharacterError {
invalid_char: char,
@ -458,7 +458,7 @@ impl std::error::Error for ParseDenominationError {
#[non_exhaustive]
pub struct MissingDenominationError;
/// Parsing error, unknown denomination.
/// Error returned when parsing an unknown denomination.
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct UnknownDenominationError(InputString);
@ -474,7 +474,7 @@ impl std::error::Error for UnknownDenominationError {
fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { None }
}
/// Parsing error, possibly confusing denomination.
/// Error returned when parsing a possibly confusing denomination.
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct PossiblyConfusingDenominationError(InputString);
@ -512,7 +512,7 @@ fn is_too_precise(s: &str, precision: usize) -> Option<usize> {
const INPUT_STRING_LEN_LIMIT: usize = 50;
/// Parse decimal string in the given denomination into a satoshi value and a
/// Parses a decimal string in the given denomination into a satoshi value and a
/// `bool` indicator for a negative amount.
fn parse_signed_to_satoshi(
mut s: &str,
@ -867,19 +867,19 @@ impl Amount {
/// The number of bytes that an amount contributes to the size of a transaction.
pub const SIZE: usize = 8; // Serialized length of a u64.
/// Create an [`Amount`] with satoshi precision and the given number of satoshis.
/// Creates an [`Amount`] with satoshi precision and the given number of satoshis.
pub const fn from_sat(satoshi: u64) -> Amount { Amount(satoshi) }
/// Gets the number of satoshis in this [`Amount`].
pub fn to_sat(self) -> u64 { self.0 }
/// Convert from a value expressing bitcoins to an [`Amount`].
/// Converts from a value expressing bitcoins to an [`Amount`].
#[cfg(feature = "alloc")]
pub fn from_btc(btc: f64) -> Result<Amount, ParseAmountError> {
Amount::from_float_in(btc, Denomination::Bitcoin)
}
/// Convert from a value expressing integer values of bitcoins to an [`Amount`]
/// Converts from a value expressing integer values of bitcoins to an [`Amount`]
/// in const context.
///
/// # Panics
@ -900,7 +900,7 @@ impl Amount {
}
}
/// Parse a decimal string as a value in the given denomination.
/// Parses a decimal string as a value in the given denomination.
///
/// Note: This only parses the value string. If you want to parse a value
/// with denomination, use [`FromStr`].
@ -922,7 +922,7 @@ impl Amount {
Amount::from_str_in(amt, denom).map_err(Into::into)
}
/// Express this [`Amount`] as a floating-point value in the given denomination.
/// Expresses this [`Amount`] as a floating-point value in the given denomination.
///
/// Please be aware of the risk of using floating-point numbers.
#[cfg(feature = "alloc")]
@ -930,7 +930,7 @@ impl Amount {
f64::from_str(&self.to_string_in(denom)).unwrap()
}
/// Express this [`Amount`] as a floating-point value in Bitcoin.
/// Expresses this [`Amount`] as a floating-point value in Bitcoin.
///
/// Please be aware of the risk of using floating-point numbers.
///
@ -944,7 +944,7 @@ impl Amount {
#[cfg(feature = "alloc")]
pub fn to_btc(self) -> f64 { self.to_float_in(Denomination::Bitcoin) }
/// Convert this [`Amount`] in floating-point notation with a given
/// Converts this [`Amount`] in floating-point notation with a given
/// denomination.
/// Can return error if the amount is too big, too precise or negative.
///
@ -959,7 +959,7 @@ impl Amount {
Amount::from_str_in(&value.to_string(), denom)
}
/// Create an object that implements [`fmt::Display`] using specified denomination.
/// Creates an object that implements [`fmt::Display`] using specified denomination.
pub fn display_in(self, denomination: Denomination) -> Display {
Display {
sats_abs: self.to_sat(),
@ -968,7 +968,7 @@ impl Amount {
}
}
/// Create an object that implements [`fmt::Display`] dynamically selecting denomination.
/// Creates an object that implements [`fmt::Display`] dynamically selecting denomination.
///
/// This will use BTC for values greater than or equal to 1 BTC and satoshis otherwise. To
/// avoid confusion the denomination is always shown.
@ -980,7 +980,7 @@ impl Amount {
}
}
/// Format the value of this [`Amount`] in the given denomination.
/// Formats the value of this [`Amount`] in the given denomination.
///
/// Does not include the denomination.
#[rustfmt::skip]
@ -989,13 +989,13 @@ impl Amount {
fmt_satoshi_in(self.to_sat(), false, f, denom, false, FormatOptions::default())
}
/// Get a string number of this [`Amount`] in the given denomination.
/// Returns a formatted string of this [`Amount`] in the given denomination.
///
/// Does not include the denomination.
#[cfg(feature = "alloc")]
pub fn to_string_in(self, denom: Denomination) -> String { self.display_in(denom).to_string() }
/// Get a formatted string of this [`Amount`] in the given denomination,
/// Returns a formatted string of this [`Amount`] in the given denomination,
/// suffixed with the abbreviation for the denomination.
#[cfg(feature = "alloc")]
pub fn to_string_with_denomination(self, denom: Denomination) -> String {
@ -1053,7 +1053,7 @@ impl Amount {
/// On overflow, panics in debug mode, wraps in release mode.
pub fn unchecked_sub(self, rhs: Amount) -> Amount { Self(self.0 - rhs.0) }
/// Convert to a signed amount.
/// Converts to a signed amount.
pub fn to_signed(self) -> Result<SignedAmount, OutOfRangeError> {
if self.to_sat() > SignedAmount::MAX.to_sat() as u64 {
Err(OutOfRangeError::too_big(true))
@ -1373,45 +1373,58 @@ impl SignedAmount {
/// - `-1` if the amount is negative
pub fn signum(self) -> i64 { self.0.signum() }
/// Checks if this [`SignedAmount`] is positive.
///
/// Returns `true` if this [`SignedAmount`] is positive and `false` if
/// this [`SignedAmount`] is zero or negative.
pub fn is_positive(self) -> bool { self.0.is_positive() }
/// Checks if this [`SignedAmount`] is negative.
///
/// Returns `true` if this [`SignedAmount`] is negative and `false` if
/// this [`SignedAmount`] is zero or positive.
pub fn is_negative(self) -> bool { self.0.is_negative() }
/// Get the absolute value of this [`SignedAmount`].
/// Returns the absolute value of this [`SignedAmount`].
///
/// Consider using `unsigned_abs` which is often more practical.
///
/// Returns [`None`] if overflow occurred. (`self == MIN`)
pub fn checked_abs(self) -> Option<SignedAmount> { self.0.checked_abs().map(SignedAmount) }
/// Checked addition.
///
/// Returns [`None`] if overflow occurred.
pub fn checked_add(self, rhs: SignedAmount) -> Option<SignedAmount> {
self.0.checked_add(rhs.0).map(SignedAmount)
}
/// Checked subtraction.
///
/// Returns [`None`] if overflow occurred.
pub fn checked_sub(self, rhs: SignedAmount) -> Option<SignedAmount> {
self.0.checked_sub(rhs.0).map(SignedAmount)
}
/// Checked multiplication.
///
/// Returns [`None`] if overflow occurred.
pub fn checked_mul(self, rhs: i64) -> Option<SignedAmount> {
self.0.checked_mul(rhs).map(SignedAmount)
}
/// Checked integer division.
///
/// Be aware that integer division loses the remainder if no exact division
/// can be made.
///
/// Returns [`None`] if overflow occurred.
pub fn checked_div(self, rhs: i64) -> Option<SignedAmount> {
self.0.checked_div(rhs).map(SignedAmount)
}
/// Checked remainder.
///
/// Returns [`None`] if overflow occurred.
pub fn checked_rem(self, rhs: i64) -> Option<SignedAmount> {
self.0.checked_rem(rhs).map(SignedAmount)
@ -1436,6 +1449,7 @@ impl SignedAmount {
pub fn unchecked_sub(self, rhs: SignedAmount) -> SignedAmount { Self(self.0 - rhs.0) }
/// Subtraction that doesn't allow negative [`SignedAmount`]s.
///
/// Returns [`None`] if either [`self`], `rhs` or the result is strictly negative.
pub fn positive_sub(self, rhs: SignedAmount) -> Option<SignedAmount> {
if self.is_negative() || rhs.is_negative() || rhs > self {
@ -1445,7 +1459,7 @@ impl SignedAmount {
}
}
/// Convert to an unsigned amount.
/// Converts to an unsigned amount.
pub fn to_unsigned(self) -> Result<Amount, OutOfRangeError> {
if self.is_negative() {
Err(OutOfRangeError::negative())
@ -1558,9 +1572,9 @@ impl core::iter::Sum for SignedAmount {
}
}
/// Calculate the sum over the iterator using checked arithmetic.
/// Calculates the sum over the iterator using checked arithmetic.
pub trait CheckedSum<R>: private::SumSeal<R> {
/// Calculate the sum over the iterator using checked arithmetic. If an over or underflow would
/// Calculates the sum over the iterator using checked arithmetic. If an over or underflow would
/// happen it returns `None`.
fn checked_sum(self) -> Option<R>;
}

2
units/src/block.rs
View File

@ -155,7 +155,7 @@ impl TryFrom<BlockInterval> for relative::Height {
}
}
/// The block interval is too big to be used as a relative lock time.
/// Error returned when the block interval is too big to be used as a relative lock time.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TooBigForRelativeBlockHeightError(u32);

10
units/src/fee_rate.rs
View File

@ -91,14 +91,14 @@ impl FeeRate {
Some(Amount::from_sat(sats))
}
/// Calculates fee by multiplying this fee rate by weight, in weight units, returning `None`
/// if overflow occurred.
/// Calculates the fee by multiplying this fee rate by weight, in weight units, returning `None`
/// if an overflow occurred.
///
/// This is equivalent to `Self::checked_mul_by_weight()`.
pub fn fee_wu(self, weight: Weight) -> Option<Amount> { self.checked_mul_by_weight(weight) }
/// Calculates fee by multiplying this fee rate by weight, in virtual bytes, returning `None`
/// if overflow occurred.
/// Calculates the fee by multiplying this fee rate by weight, in virtual bytes, returning `None`
/// if an overflow occurred.
///
/// This is equivalent to converting `vb` to `weight` using `Weight::from_vb` and then calling
/// `Self::fee_wu(weight)`.
@ -122,7 +122,7 @@ impl From<FeeRate> for u64 {
fn from(value: FeeRate) -> Self { value.to_sat_per_kwu() }
}
/// Computes ceiling so that fee computation is conservative.
/// Computes the ceiling so that the fee computation is conservative.
impl Mul<FeeRate> for Weight {
type Output = Amount;

6
units/src/locktime/absolute.rs
View File

@ -1,6 +1,6 @@
// SPDX-License-Identifier: CC0-1.0
//! Provides type `Height` and `Time` types used by the `rust-bitcoin` `absolute::LockTime` type.
//! Provides `Height` and `Time` types used by the `rust-bitcoin` `absolute::LockTime` type.
use core::fmt;
@ -41,7 +41,7 @@ impl Height {
/// Creates a `Height` from a hex string.
///
/// The input string is may or may not contain a typical hex prefix e.g., `0x`.
/// The input string may or may not contain a typical hex prefix e.g., `0x`.
pub fn from_hex(s: &str) -> Result<Self, ParseHeightError> {
parse_hex(s, Self::from_consensus)
}
@ -139,7 +139,7 @@ impl Time {
/// Creates a `Time` from a hex string.
///
/// The input string is may or may not contain a typical hex prefix e.g., `0x`.
/// The input string may or may not contain a typical hex prefix e.g., `0x`.
pub fn from_hex(s: &str) -> Result<Self, ParseTimeError> { parse_hex(s, Self::from_consensus) }
/// Constructs a new block time.

10
units/src/locktime/relative.rs
View File

@ -1,6 +1,6 @@
// SPDX-License-Identifier: CC0-1.0
//! Provides type `Height` and `Time` types used by the `rust-bitcoin` `relative::LockTime` type.
//! Provides `Height` and `Time` types used by the `rust-bitcoin` `relative::LockTime` type.
use core::fmt;
@ -64,13 +64,13 @@ impl Time {
/// The maximum relative block time (33,554,432 seconds or approx 388 days).
pub const MAX: Self = Time(u16::MAX);
/// Create a [`Time`] using time intervals where each interval is equivalent to 512 seconds.
/// Creates a [`Time`] using time intervals where each interval is equivalent to 512 seconds.
///
/// Encoding finer granularity of time for relative lock-times is not supported in Bitcoin.
#[inline]
pub const fn from_512_second_intervals(intervals: u16) -> Self { Time(intervals) }
/// Create a [`Time`] from seconds, converting the seconds into 512 second interval with
/// Creates a [`Time`] from seconds, converting the seconds into 512 second interval with
/// truncating division.
///
/// # Errors
@ -87,8 +87,8 @@ impl Time {
}
}
/// Create a [`Time`] from seconds, converting the seconds into 512 second interval with ceiling
/// division.
/// Creates a [`Time`] from seconds, converting the seconds into 512 second intervals with
/// ceiling division.
///
/// # Errors
///

45
units/src/parse.rs
View File

@ -160,11 +160,11 @@ macro_rules! impl_parse_str {
}
}
/// Removes the prefix `0x` (or `0X`) from hex string.
/// Removes the prefix `0x` (or `0X`) from a hex string.
///
/// # Errors
///
/// If input string does not contain a prefix.
/// If the input string does not contain a prefix.
pub fn hex_remove_prefix(s: &str) -> Result<&str, PrefixedHexError> {
if let Some(checked) = s.strip_prefix("0x") {
Ok(checked)
@ -175,11 +175,11 @@ pub fn hex_remove_prefix(s: &str) -> Result<&str, PrefixedHexError> {
}
}
/// Checks hex string does not have a prefix `0x` (or `0X`).
/// Checks a hex string does not have a prefix `0x` (or `0X`).
///
/// # Errors
///
/// If input string contains a prefix.
/// If the input string contains a prefix.
pub fn hex_check_unprefixed(s: &str) -> Result<&str, UnprefixedHexError> {
if s.starts_with("0x") || s.starts_with("0X") {
return Err(ContainsPrefixError::new(s.into()).into());
@ -203,8 +203,8 @@ pub fn hex_u32(s: &str) -> Result<u32, ParseIntError> {
///
/// # Errors
///
/// - If input string does not contain a `0x` (or `0X`) prefix.
/// - If input string is not a valid hex encoding of a `u32`.
/// - If the input string does not contain a `0x` (or `0X`) prefix.
/// - If the input string is not a valid hex encoding of a `u32`.
pub fn hex_u32_prefixed(s: &str) -> Result<u32, PrefixedHexError> {
let checked = hex_remove_prefix(s)?;
Ok(hex_u32_unchecked(checked)?)
@ -214,19 +214,19 @@ pub fn hex_u32_prefixed(s: &str) -> Result<u32, PrefixedHexError> {
///
/// # Errors
///
/// - If input string contains a `0x` (or `0X`) prefix.
/// - If input string is not a valid hex encoding of a `u32`.
/// - If the input string contains a `0x` (or `0X`) prefix.
/// - If the input string is not a valid hex encoding of a `u32`.
pub fn hex_u32_unprefixed(s: &str) -> Result<u32, UnprefixedHexError> {
let checked = hex_check_unprefixed(s)?;
Ok(hex_u32_unchecked(checked)?)
}
/// Parses a `u32` from a hex string.
/// Parses a `u32` from an unprefixed hex string without first checking for a prefix.
///
/// # Errors
///
/// - If input string is not a valid hex encoding of a `u32`.
/// - With `InvalidDigit` due to the `x` if there is a prefix.
/// - If the input string contains a `0x` (or `0X`) prefix, returns `InvalidDigit` due to the `x`.
/// - If the input string is not a valid hex encoding of a `u32`.
pub fn hex_u32_unchecked(s: &str) -> Result<u32, ParseIntError> {
u32::from_str_radix(s, 16).map_err(|error| ParseIntError {
input: s.into(),
@ -252,8 +252,8 @@ pub fn hex_u128(s: &str) -> Result<u128, ParseIntError> {
///
/// # Errors
///
/// - If input string does not contain a `0x` (or `0X`) prefix.
/// - If input string is not a valid hex encoding of a `u128`.
/// - If the input string does not contain a `0x` (or `0X`) prefix.
/// - If the input string is not a valid hex encoding of a `u128`.
pub fn hex_u128_prefixed(s: &str) -> Result<u128, PrefixedHexError> {
let checked = hex_remove_prefix(s)?;
Ok(hex_u128_unchecked(checked)?)
@ -263,19 +263,19 @@ pub fn hex_u128_prefixed(s: &str) -> Result<u128, PrefixedHexError> {
///
/// # Errors
///
/// - If input string contains a `0x` (or `0X`) prefix.
/// - If input string is not a valid hex encoding of a `u128`.
/// - If the input string contains a `0x` (or `0X`) prefix.
/// - If the input string is not a valid hex encoding of a `u128`.
pub fn hex_u128_unprefixed(s: &str) -> Result<u128, UnprefixedHexError> {
let checked = hex_check_unprefixed(s)?;
Ok(hex_u128_unchecked(checked)?)
}
/// Parses a `u128` from a hex string.
/// Parses a `u128` from an unprefixed hex string without first checking for a prefix.
///
/// # Errors
///
/// - If input string is not a valid hex encoding of a `u128`.
/// - With `InvalidDigit` due to the `x` if there is a prefix.
/// - If the input string contains a `0x` (or `0X`) prefix, returns `InvalidDigit` due to the `x`.
/// - If the input string is not a valid hex encoding of a `u128`.
pub fn hex_u128_unchecked(s: &str) -> Result<u128, ParseIntError> {
u128::from_str_radix(s, 16).map_err(|error| ParseIntError {
input: s.into(),
@ -296,8 +296,7 @@ pub(crate) fn hex_remove_optional_prefix(s: &str) -> &str {
}
}
/// Error returned when parsing integer from an supposedly prefixed hex string for
/// a type that can be created infallibly from an integer.
/// Error returned when parsing an integer from a hex string that is supposed to contain a prefix.
#[derive(Debug, Clone, Eq, PartialEq)]
pub enum PrefixedHexError {
/// Hex string is missing prefix.
@ -337,7 +336,7 @@ impl From<ParseIntError> for PrefixedHexError {
fn from(e: ParseIntError) -> Self { Self::ParseInt(e) }
}
/// Error returned when parsing integer from an supposedly un-prefixed hex string.
/// Error returned when parsing an integer from a hex string that is not supposed to contain a prefix.
#[derive(Debug, Clone, Eq, PartialEq)]
pub enum UnprefixedHexError {
/// Hex string contains prefix.
@ -377,7 +376,7 @@ impl From<ParseIntError> for UnprefixedHexError {
fn from(e: ParseIntError) -> Self { Self::ParseInt(e) }
}
/// Error when hex string is missing a prefix (e.g. `0x`).
/// Error returned when a hex string is missing a prefix (e.g. `0x`).
#[derive(Debug, Clone, Eq, PartialEq)]
pub struct MissingPrefixError {
hex: String,
@ -397,7 +396,7 @@ impl fmt::Display for MissingPrefixError {
#[cfg(feature = "std")]
impl std::error::Error for MissingPrefixError {}
/// Error when hex string contains a prefix (e.g. `0x`).
/// Error when hex string contains a prefix (e.g. 0x).
#[derive(Debug, Clone, Eq, PartialEq)]
pub struct ContainsPrefixError {
hex: String,

4
units/src/weight.rs
View File

@ -52,12 +52,12 @@ impl Weight {
/// Constructs `Weight` from kilo weight units returning `None` if an overflow occurred.
pub fn from_kwu(wu: u64) -> Option<Self> { wu.checked_mul(1000).map(Weight) }
/// Constructs `Weight` from virtual bytes, returning `None` on overflow.
/// Constructs `Weight` from virtual bytes, returning `None` if an overflow occurred.
pub fn from_vb(vb: u64) -> Option<Self> {
vb.checked_mul(Self::WITNESS_SCALE_FACTOR).map(Weight::from_wu)
}
/// Constructs `Weight` from virtual bytes panicking on overflow.
/// Constructs `Weight` from virtual bytes panicking if an overflow occurred.
///
/// # Panics
///