There is a range of different wordings used in the docs of constructor
type functions.
Change all to start with `Constructs a new` or `Constructs an empty`.
In functions that act like constructors there is a mixture of the usage
of `creates` and `constructs`.
Replace all occurrences of `creates` with `constructs` in the first line
of docs of constructor like functions.
81d8699b55 units: Put no_std up top (Tobin C. Harding)
3e332c3839 amount: Fix docs on FromStr (Tobin C. Harding)
5bec76aa51 amount: Fix rustdocs (Tobin C. Harding)
41c80cc476 amount: Improve docs on div by weight (Tobin C. Harding)
2b4a61739a Add type to debug output for Amount (Tobin C. Harding)
42e5043b33 Add from_int_btc group of functions (Tobin C. Harding)
Pull request description:
Improve the `amount` module by doing:
- Patch 1: Add/update `from_int_btc` and `from_int_btc_const` functions
- Patch 2: Add type to debug output for `Amount`
- Patch 3: Fix incorrect docs
- Patch 4: Make docs use correct style and be uniform across the two amount types
- Patch 5: Fix docs on `FromStr`
ACKs for top commit:
apoelstra:
ACK 81d8699b55dad570247cb14d2b3eea64270a83cf; successfully ran local tests
jamillambert:
ACK 81d8699b55
Tree-SHA512: ddd6e02b4cd9a9aa8cbdd2d2f7ae289a6bcca9eb002ef0c6d83a6eca950b2cd08f5918286bb33e814f321e3bfe83fdf75ae051cf8f91ee45d3e4abe76c1c2a4c
The `no_std` attribute has significant ramifications, as opposed to the
clippy attributes etc.
Put the `no_std` attribute up top so it catches the eye. This is also
uniform with other crates in this repo.
The docs on `FromStr` say "string slice is zero" but actually mean to
document the behaviour when the value represented is zero.
Also the fact that `FromStr` returns an error if parsing fails is self
evident.
Fix the rustdocs on `Amount` and `SignedAmount` by doing:
- Make them uniform
- Use correct style (looks like `SignedAmount` got left behind when we
improved `Amount`)
Add/update the from_int group of functions to provide one that errors
and one that is const and panics (errors in const context are not useful
because one cannot call `unwrap` in const context).
In an effort to reduce requirement for `alloc`; remove the `String` and
use `InputString` in the hex prefix related error types.
Tested with:
(Note in test code we have to use `"cafe".to_owned()` before this patch
is applied.)
rust```
#[test]
fn hex_prefix_errors() {
let err = hex_remove_prefix("cafe").unwrap_err();
std::println!("{}", err);
std::println!("{:?}", err);
let err = hex_check_unprefixed("0xcafe").unwrap_err();
std::println!("{}", err);
std::println!("{:?}", err);
}
```
Before:
hex string is missing a prefix (e.g. 0x): cafe
MissingPrefixError { hex: "cafe" }
hex string contains a prefix: 0xcafe
ContainsPrefixError { hex: "0xcafe" }
After:
failed to parse 'cafe' as hex because it is missing the '0x' prefix
MissingPrefixError { hex: InputString("cafe") }
failed to parse '0xcafe' as hex because it contains the '0x' prefix
ContainsPrefixError { hex: InputString("0xcafe") }
3f2e760d1f Replace String with InputString in ParseIntError (Tobin C. Harding)
aa5c78430c Replace invalidInteger with ParseIntError (Tobin C. Harding)
9b7a706bfd Remove From<ParseIntError> (Tobin C. Harding)
c90f4b6033 Fix bug in error output (Tobin C. Harding)
c986b2f620 internals: Move error.rs to error/mod.rs (Tobin C. Harding)
Pull request description:
This PR hopefully clears the way for removing many of the `alloc` feature gates in `units` and `primitives`
The three final patches were tested by adding the following test to `units::locktime::absolute`:
```rust
#[test]
pub fn debug_absolute_error_conversion_height() {
let invalid_height = LOCK_TIME_THRESHOLD + 1;
let err = Height::from_consensus(invalid_height).unwrap_err();
std::println!("{:?}", err);
std::println!("{}", err);
let invalid_time = LOCK_TIME_THRESHOLD - 1;
let err = Time::from_consensus(invalid_time).unwrap_err();
std::println!("{:?}", err);
std::println!("{}", err);
let invalid_height = std::format!("{:x}", LOCK_TIME_THRESHOLD + 1);
let err = Height::from_hex(&invalid_height).unwrap_err();
std::println!("{:?}", err);
std::println!("{}", err);
let invalid_time = std::format!("{:x}", LOCK_TIME_THRESHOLD - 1);
let err = Time::from_hex(&invalid_time).unwrap_err();
std::println!("{:?}", err);
std::println!("{}", err);
let err = Height::from_hex("somerandomshit").unwrap_err();
std::println!("{:?}", err);
std::println!("{}", err);
let err = Time::from_hex("somerandomshit").unwrap_err();
std::println!("{:?}", err);
std::println!("{}", err);
}
```
Gives the following output (the last four lines is the bit that changes, the rest just proves we don't break other variants)
On commit: `d47ff1c25 Remove From<ParseIntError>`
ConversionError { unit: Blocks, input: 500000001 }
invalid lock time value 500000001, expected lock-by-blockheight (must be < 500000000)
ConversionError { unit: Seconds, input: 499999999 }
invalid lock time value 499999999, expected lock-by-blocktime (must be >= 500000000)
ParseHeightError(Conversion(500000001))
block height 500000001 is above limit 499999999
ParseTimeError(Conversion(499999999))
block height 499999999 is below limit 500000000
ParseHeightError(InvalidInteger { source: ParseIntError { kind: InvalidDigit }, input: "somerandomshit" })
failed to parse somerandomshit as block height
ParseTimeError(InvalidInteger { source: ParseIntError { kind: InvalidDigit }, input: "somerandomshit" })
failed to parse somerandomshit as block time
On commit: `0155a0d9a Replace invalidInteger with ParseIntError`
ConversionError { unit: Blocks, input: 500000001 }
invalid lock time value 500000001, expected lock-by-blockheight (must be < 500000000)
ConversionError { unit: Seconds, input: 499999999 }
invalid lock time value 499999999, expected lock-by-blocktime (must be >= 500000000)
ParseHeightError(Conversion(500000001))
block height 500000001 is above limit 499999999
ParseTimeError(Conversion(499999999))
block height 499999999 is below limit 500000000
ParseHeightError(ParseInt(ParseIntError { input: "somerandomshit", bits: 32, is_signed: true, source: ParseIntError { kind: InvalidDigit } }))
failed to parse somerandomshit as block height
ParseTimeError(ParseInt(ParseIntError { input: "somerandomshit", bits: 32, is_signed: true, source: ParseIntError { kind: InvalidDigit } }))
failed to parse somerandomshit as block time
On Commit: `3f2e760d1 Replace String with InputString in ParseIntError`
ConversionError { unit: Blocks, input: 500000001 }
invalid lock time value 500000001, expected lock-by-blockheight (must be < 500000000)
ConversionError { unit: Seconds, input: 499999999 }
invalid lock time value 499999999, expected lock-by-blocktime (must be >= 500000000)
ParseHeightError(Conversion(500000001))
block height 500000001 is above limit 499999999
ParseTimeError(Conversion(499999999))
block time 499999999 is below limit 500000000
ParseHeightError(ParseInt(ParseIntError { input: InputString("somerandomshit"), bits: 32, is_signed: true, source: ParseIntError { kind: InvalidDigit } }))
failed to parse 'somerandomshit' as absolute Height/Time (block height)
ParseTimeError(ParseInt(ParseIntError { input: InputString("somerandomshit"), bits: 32, is_signed: true, source: ParseIntError { kind: InvalidDigit } }))
failed to parse 'somerandomshit' as absolute Height/Time (block time)
ACKs for top commit:
apoelstra:
ACK 3f2e760d1fef2951f93a2554cd53340b0d7a6e0b; successfully ran local tests; nice!
Tree-SHA512: f7fd55acfb83082419db22c24a6b375c20e2631263401e500410c5b5659463f06dc4bdb145621e475dc15d75e764668cdcbf8f88006a487248a05fdb237ad136
Currently the `ParseIntError` contains an owned copy of the input
string, this is causing us to have to use `alloc` everywhere.
We already have a alloc-friendly string replacement type, the
`InputString` - use it.
We have a special type for wrapping integer parsing errors, use it.
To test this I added the following tests:
#[test]
pub fn debug_absolute_error_conversion_height() {
let invalid_height = LOCK_TIME_THRESHOLD + 1;
let _ = Height::from_consensus(invalid_height).unwrap();
}
#[test]
pub fn debug_absolute_error_conversion_time() {
let invalid_time = LOCK_TIME_THRESHOLD - 1;
let _ = Time::from_consensus(invalid_time).unwrap();
}
#[test]
#[cfg(feature = "std")]
pub fn debug_absolute_error_conversion_height_string() {
let invalid_height = std::format!("{:x}", LOCK_TIME_THRESHOLD + 1);
let _ = Height::from_hex(&invalid_height).unwrap();
}
#[test]
#[cfg(feature = "std")]
pub fn debug_absolute_error_conversion_time_string() {
let invalid_time = std::format!("{:x}", LOCK_TIME_THRESHOLD - 1);
let _ = Time::from_hex(&invalid_time).unwrap();
}
#[test]
#[cfg(feature = "std")]
pub fn debug_absolute_error_height_invalid_hex_string() {
let _ = Height::from_hex("somerandomshit").unwrap();
}
#[test]
#[cfg(feature = "std")]
pub fn debug_absolute_error_time_invalid_hex_string() {
let _ = Time::from_hex("somerandomshit").unwrap();
}
Which resulted in the following output
Before:
---- locktime::absolute::tests::debug_absolute_error_conversion_height stdout ----
thread 'locktime::absolute::tests::debug_absolute_error_conversion_height' panicked at units/src/locktime/absolute.rs:431:56:
called `Result::unwrap()` on an `Err` value: ConversionError { unit: Blocks, input: 500000001 }
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
---- locktime::absolute::tests::debug_absolute_error_conversion_height_string stdout ----
thread 'locktime::absolute::tests::debug_absolute_error_conversion_height_string' panicked at units/src/locktime/absolute.rs:444:51:
called `Result::unwrap()` on an `Err` value: ParseHeightError(Conversion(500000001))
---- locktime::absolute::tests::debug_absolute_error_conversion_time stdout ----
thread 'locktime::absolute::tests::debug_absolute_error_conversion_time' panicked at units/src/locktime/absolute.rs:437:52:
called `Result::unwrap()` on an `Err` value: ConversionError { unit: Seconds, input: 499999999 }
---- locktime::absolute::tests::debug_absolute_error_height_invalid_hex_string stdout ----
thread 'locktime::absolute::tests::debug_absolute_error_height_invalid_hex_string' panicked at units/src/locktime/absolute.rs:457:52:
called `Result::unwrap()` on an `Err` value: ParseHeightError(InvalidInteger { source: ParseIntError { kind: InvalidDigit }, input: "somerandomshit" })
---- locktime::absolute::tests::debug_absolute_error_conversion_time_string stdout ----
thread 'locktime::absolute::tests::debug_absolute_error_conversion_time_string' panicked at units/src/locktime/absolute.rs:451:47:
called `Result::unwrap()` on an `Err` value: ParseTimeError(Conversion(499999999))
---- locktime::absolute::tests::debug_absolute_error_time_invalid_hex_string stdout ----
thread 'locktime::absolute::tests::debug_absolute_error_time_invalid_hex_string' panicked at units/src/locktime/absolute.rs:464:50:
called `Result::unwrap()` on an `Err` value: ParseTimeError(InvalidInteger { source: ParseIntError { kind: InvalidDigit }, input: "somerandomshit" })
After:
---- locktime::absolute::tests::debug_absolute_error_conversion_height stdout ----
thread 'locktime::absolute::tests::debug_absolute_error_conversion_height' panicked at units/src/locktime/absolute.rs:432:56:
called `Result::unwrap()` on an `Err` value: ConversionError { unit: Blocks, input: 500000001 }
---- locktime::absolute::tests::debug_absolute_error_conversion_height_string stdout ----
thread 'locktime::absolute::tests::debug_absolute_error_conversion_height_string' panicked at units/src/locktime/absolute.rs:445:51:
called `Result::unwrap()` on an `Err` value: ParseHeightError(Conversion(500000001))
---- locktime::absolute::tests::debug_absolute_error_conversion_time stdout ----
thread 'locktime::absolute::tests::debug_absolute_error_conversion_time' panicked at units/src/locktime/absolute.rs:438:52:
called `Result::unwrap()` on an `Err` value: ConversionError { unit: Seconds, input: 499999999 }
---- locktime::absolute::tests::debug_absolute_error_conversion_time_string stdout ----
thread 'locktime::absolute::tests::debug_absolute_error_conversion_time_string' panicked at units/src/locktime/absolute.rs:452:47:
called `Result::unwrap()` on an `Err` value: ParseTimeError(Conversion(499999999))
---- locktime::absolute::tests::debug_absolute_error_height_invalid_hex_string stdout ----
thread 'locktime::absolute::tests::debug_absolute_error_height_invalid_hex_string' panicked at units/src/locktime/absolute.rs:458:52:
called `Result::unwrap()` on an `Err` value: ParseHeightError(ParseInt(ParseIntError { input: "somerandomshit", bits: 32, is_signed: false, source: ParseIntError { kind: InvalidDigit } }))
---- locktime::absolute::tests::debug_absolute_error_time_invalid_hex_string stdout ----
thread 'locktime::absolute::tests::debug_absolute_error_time_invalid_hex_string' panicked at units/src/locktime/absolute.rs:465:50:
called `Result::unwrap()` on an `Err` value: ParseTimeError(ParseInt(ParseIntError { input: "somerandomshit", bits: 32, is_signed: false, source: ParseIntError { kind: InvalidDigit } }))
The errors in `units::locktime::absolute` are complex, I'd like to make
them more simple so they are more understandable.
I have no clue why this is implemented - remove it.
This has been fixed and we use nightly to lint so we have access to the
merged fix.
Removing the attribute uncovers a bunch of real lint warnings, fix
them while we are at it.
In an effort to make the `amount` module more readable move the
`SignedAmount` type to a private submodule.
Re-export everything so this is not a breaking change.
Code move and re-exports only.
When we move `SignedAmount` to a submodule linking to `self` introduces
a clippy warning, I'm not exactly sure why but lets remove the link in
preparation for the move.
In an effort to make the `amount` module more readable move the `Amount`
type to a private submodule.
Re-export everything so this is not a breaking change.
Code move and re-exports only.
There is _a lot_ of error types in the `amount` module. Move them to a
separate `error` module.
Add a bunch of `pub(super)` to keep things private to the `amount`
module.
Eventually we will want to close all these errors.
In preparation for splitting the error types out of `amount.rs` into
their own file move the `amount.rs` file to `amount/mod.rs`.
File move only, no other changes.
88b53a471e Unify deprecated note field format (Jamil Lambert, PhD)
Pull request description:
Following the suggestion in Issue #3306 all the deprecated note fields have been changed to be lower case and in the format "use `abc` instead".
ACKs for top commit:
tcharding:
ACK 88b53a471e
apoelstra:
ACK 88b53a471e successfully ran local tests
Tree-SHA512: 5c20eda7140f37ce78eb58dfdf03ecc11a67fcb10f294d860e81eaaee696e3a4209516017a9885cef9bfff1aa69b845534d139578b674933770fa24d59e4275f
We use `TBD` in our `deprecated` string and it was discovered that there
is an exception on this string so as not to warn because it is used
internally by the Rust language. However there is a special lint to
enable warnings, lets use it.
Add `#![warn(deprecated_in_future)]` to the coding conventions section
of all crates except `fuzz`.
a0c58a4a8b Add checked weight division to Amount (yancy)
8def40a991 Add assertions to checked_weight_mul test (yancy)
16ce70d3a6 Add div_by_weight test to fee_rate (yancy)
Pull request description:
Adds the checked variant of `amount / weight`. I also added a test to the non-checked version for comparison so the reviewer knows they compute the same way (integer division rounded down).
Also added assertion to `checked_weight_mul test` showing the results are rounded up.
ACKs for top commit:
tcharding:
ACK a0c58a4a8b
apoelstra:
ACK a0c58a4a8b successfully ran local tests
Tree-SHA512: cf14123ed261d100e3261a720c26f8c10368f05225e32eaa246f25ab766d20515db5feb98335d4e3e08a8146a70db65ff64670da3f75e7764e8f86ef534d2663
07a529a132 Bump version of bitcoin-units to 0.2.0 (Tobin C. Harding)
148711a4c6 units: Use double ## in changelog entries (Tobin C. Harding)
80e600ba0c units: Copy 0.1.2 release notes (Tobin C. Harding)
Pull request description:
In preparation for releasing `units v0.2.0` bump the version number, add a changelog entry, update the lock files, and depend on the new version in all crates that depend on `units`.
Close: #3095
ACKs for top commit:
apoelstra:
ACK 07a529a132 successfully ran local tests
Tree-SHA512: 98a75d485ded6225551a5fc4b4a14d8efecc76911a720f959044cdd62781024a8787f258f171ed297705f5ab470f9a88a81ad5d255c9e03c1e22857615ad2e6d
de319670ae feat: Create relative lock times at compile time (Christian Lewe)
53e1fb6b0c feat: Create absolute lock time at compile time (Christian Lewe)
Pull request description:
I noticed that I cannot create lock times as compile-time constants. This PR tries to remedy this issue by marking lock time constructors as `const`.
Because the `internals` crate depends on the `units` crate in a way that I don't fully understand yet, this PR updates the `units` crate only.
If `from_consensus` is being kept non-`const` by design, to keep the API flexible to future changes, then please close this PR. In this case, I overlooked existing discussions.
ACKs for top commit:
apoelstra:
ACK de319670ae successfully ran local tests; good start; should backport
tcharding:
ACK de319670ae
Tree-SHA512: 69f9147707bcf8f91f755dd6d1be5ed08945e775ee46918e33d77a9d07ce474047a80ed1226134a3914ead51d1ddbbc657552ca934dc3c079b92ad3d50b13152
Also mark these methods as const. Because <u32 as From<u16>>::from
is not available in const contexts, I had to cast u16 as u32. I try to
avoid casts as much as I can, but in this case a cast seems unavoidable.
Casting u16 as u32 should be safe on all architectures.
Mark the from_consensus and to_consensus methods of the absolute
lock time structs as const. In theory. these methods do some sanity
checking and wrap a u32 value in a newtype. This should be possible
to do in const. Marking the methods as const should not break existing
call sites.
In preparation for releasing `units v0.2.0` bump the version number,
add a changelog entry, update the lock files, and depend on the new
version in all crates that depend on `units`.
yancy
Jamil Lambert, PhD
merge-script
Tobin C. Harding
Fmt Bot
Casey Rodarmor
Christian Lewe