Commit Graph

564 Commits

Author SHA1 Message Date
Jamil Lambert f22e997587
Use parameters instead of arguments in rustdocs
The rustdocs use both `# Parameters` and `# Arguments` to mean the same
thing.

Change all of them to `# Parameters` to be consistent.
2025-04-22 10:43:13 +01:00
merge-script 8ca3a430c7
Merge rust-bitcoin/rust-bitcoin#4336: units: Make minor improvements to `MathOp`
0f62c9a582 units: Make minor improvements to MathOp (Tobin C. Harding)

Pull request description:

  Follow up from #4312, improve the `MathOp` type by:

  - Do not provide public constructor
  - Add cast protection

ACKs for top commit:
  apoelstra:
    ACK 0f62c9a5822a813be5c6f6b19d160458243f174a; successfully ran local tests
  Kixunil:
    ACK 0f62c9a582

Tree-SHA512: dbb06c5afd8df5364a2aec12b7c8632620a1e8f3955b83e91a9b4f5c2e0daaa1ecdb050d8e395e95bf018d718847cddbf3338bd89f70cbb0382bf5e080d5cf21
2025-04-20 16:35:47 +00:00
Tobin C. Harding 6323867c65
Run the formatter 2025-04-17 11:43:05 +10:00
Tobin C. Harding d5c08aef32
units: Update column width
Update column width inside the new `encapsulate` modules.

No content change.
2025-04-17 11:43:05 +10:00
Tobin C. Harding f7f1a0be8c
Add privacy boundary to BlockTime
As per policy in #4090 add a privacy boundary to the `BlockTime` type.
Use the module name `encapsulate` as is done in `amount` - its private
so the name can easily be changed later if needed.

Explicitly do not run the formatter or update rustdoc column width so
that review is easier.
2025-04-17 11:43:05 +10:00
Tobin C. Harding b3dfe0df3f
Add privacy boundary to Weight
As per policy in #4090 add a privacy boundary to the `Weight` type. Use
the module name `encapsulate` as is done in `amount` - its private so
the name can easily be changed later if needed.

Explicitly do not run the formatter or update rustdoc column width so
that review is easier.
2025-04-17 11:43:05 +10:00
Tobin C. Harding e1a14b3c2d
Add privacy boundary to FeeRate
As per policy in #4090 add a privacy boundary to the `FeeRate` type. Use
the module name `encapsulate` as is done in `amount` - its private so
the name can easily be changed later if needed.

Explicitly do not run the formatter or update rustdoc column width so
that review is easier.
2025-04-17 11:43:05 +10:00
Tobin C. Harding 4b733d4dad
Run the formatter 2025-04-17 11:43:02 +10:00
merge-script 94abc99fb0
Merge rust-bitcoin/rust-bitcoin#4318: Document the `NumOpResult` type
c30a504ea6 units: Document the NumOpResult type (Tobin C. Harding)

Pull request description:

  Document the `NumOpResult` type.

  Note that this includes two new getters on the `NumOpResult`, API hole found during review of the new docs.

  Fix: #4222

ACKs for top commit:
  apoelstra:
    ACK c30a504ea6a5140bdf5667ea42b76bdfa2457456; successfully ran local tests; nice!

Tree-SHA512: ab8d971b74ff4bb06f5737943740c5c748f6313ce1b82798c7d709f8747779efdffe0aa8ed8620afa449fd0dd502b5a2050729a538c51428215972a4f7b6ebf7
2025-04-17 11:35:03 +10:00
merge-script 9364cd1f7c
Merge rust-bitcoin/rust-bitcoin#4343: units: Go over the rendered docs for the whole crate
913360b112 Make struct titles consistent (Jamil Lambert, PhD)
afe9ddd5e6 Remove - in fee rate (Jamil Lambert, PhD)
ebc6b4a876 Make warning text bold (Jamil Lambert, PhD)

Pull request description:

  I have read through all of the `units` docs and made a few changes.

  - Highlight `Warning!` in bold in `Amount` and `SignedAmount`

  - Change the one occurrence of fee-rate to fee rate to be consistent with the rest.

  - Make all of the error structs have the same title format of `Error returned...`

  - Make all other structs have the same format concisely stating what it is opposed to what it does.

ACKs for top commit:
  tcharding:
    ACK 913360b112

Tree-SHA512: 4cb08d1dae091f5b827cf9f1e931b057c6670002146a22da54886148f3052f6ea7050fcd7f62c0d83438ef170e2f109c1a36f47a280808f31466da6f3177dd01
2025-04-16 19:10:02 +00:00
merge-script b473a2090a
Merge rust-bitcoin/rust-bitcoin#4258: units: Improve code enforcing privacy boundry
ca6c607953 Adhere to sanity rules for amount types (Tobin C. Harding)
6c614d9320 units: Fix panic message (Tobin C. Harding)

Pull request description:

  This is a follow up to #4256 - onwards and upwards!

  - Patch 1: Fix the incorrect BTC value in panic message
  - Patch 2: Strictly adhere to the sanity rules (#4090)

   Close: #4140

ACKs for top commit:
  apoelstra:
    ACK ca6c607953c03aa2dc168f58329681d9e69eee04; successfully ran local tests

Tree-SHA512: 6d7fd60830e1a0f6d6262ab02ec6e297b095d0fe8fb7737563979652e4a3b4a9477a79982201c42b08e2555fd23dc5c430549966b534bdf45f40621ae81da83a
2025-04-16 18:33:09 +00:00
merge-script 551b52c7d1
Merge rust-bitcoin/rust-bitcoin#4348: refactor: Replace fold with try_fold
812c21e2e4 refactor: Replace fold with try_fold (yancy)

Pull request description:

  The and_then combinator performs a kind of bitwise and operation on two Option types here.  This is useful since the `checked` arithmetic returns an option thereby accumulating Option types.  Therefore, either the checked arithmetic operation performs the addition of the unwrapped accumulator, or it returns None.

  Instead of using `and_then` use the provided `try_fold` method which will short circuit on `None` when the checked arithmetic is used.  Also, simplify the staring condition using `Amount:ZERO` since this is logically equivalent to using the first value if one exists.

  Lastly, by using the built in `try_fold`, it's possible the performance will be improved by making use of the short circuit ability instead of evaluating each item even when the accumulator holds a None type.

ACKs for top commit:
  apoelstra:
    ACK 812c21e2e4a868046b44728c1a6209a866452820; successfully ran local tests
  tcharding:
    ACK 812c21e2e4

Tree-SHA512: 1cfcd4fa28e2b59daf3744bb5f654f65eb9853c5a36f747cb0859783e7e46c1d02ccb296612b75f7cca10782979ce052cd670c0f23c1030e0a347000d1f6df83
2025-04-16 13:56:34 +00:00
Tobin C. Harding c30a504ea6
units: Document the NumOpResult type
The `NumOpResult` type is a bit unusual. Add thorough documentation
and example usage to it.
2025-04-16 18:17:09 +10:00
Jamil Lambert, PhD 913360b112
Make struct titles consistent
Structs had various phrasings of titles.

Make the wording consistent by concisely stating what it is, instead of
what it does.

Make the wording of all error structs consistent.
2025-04-15 21:23:31 +01:00
Jamil Lambert, PhD afe9ddd5e6
Remove - in fee rate
The rest of the rustdocs use fee rate with no hyphen when using it in
normal language, i.e. not a function argument or the type.

Change it to match the others.
2025-04-15 21:22:18 +01:00
Jamil Lambert, PhD ebc6b4a876
Make warning text bold 2025-04-15 21:22:12 +01:00
merge-script c14044e76e
Merge rust-bitcoin/rust-bitcoin#4341: units: Improve crate level docs
53837d9a2e units: Improve crate level docs (Tobin C. Harding)

Pull request description:

  Add a bit more to the crate level docs. This is a simple crate so we don't need all that much.

  Done for: C-CRATE-DOC

ACKs for top commit:
  apoelstra:
    ACK 53837d9a2e1cc70e180de39c16e2d212e958a9f3; successfully ran local tests

Tree-SHA512: 374c27a25cdc9bd4edd0755be02cad66ccccedcd69836506c1f4eb86a1254bfafe11eeb6fcc27b7efd2ab3ca0acd1daa304d482c7e5a7f84ffbcffbb1bcd21d6
2025-04-15 15:12:26 +00:00
yancy 812c21e2e4 refactor: Replace fold with try_fold
The and_then combinator performs a kind of bitwise and operation on two
Option types here.  This is useful since the `checked` arithmetic
returns an option thereby accumulating Option types.  Therefore, either
the checked arithmetic operation performs the addition of the unwrapped
accumulator, or it returns None.

Instead of using `and_then` use the provided `try_fold` method which
will short circuit on `None` when the checked arithmetic is used.  Also,
simplify the staring condition using `Amount:ZERO` since this is
logically equivalent to using the first value if one exists.

Lastly, by using the built in `try_fold`, it's possible the performance
will be improved by making use of the short circuit ability instead of
evaluating each item even when the accumulator holds a None type.
2025-04-15 08:21:11 -05:00
merge-script e5b0f9cd92
Merge rust-bitcoin/rust-bitcoin#4337: Add impls for `NumOpResult` div and mul
0361604bab Add impls for NumOpResult div and mul (Tobin C. Harding)

Pull request description:

  We recently added div and mul for combinations of `Amount`, `FeeRate`, and `Weight`. When doing so we forgot to add variations for `NumOpResult`.

ACKs for top commit:
  apoelstra:
    ACK 0361604bab6c6ef260410d0bd6e33ce24a41e775; successfully ran local tests

Tree-SHA512: 6d262b9079b8a670f32d58d49e3c7e9a79d5d795a4c9f37f6bc2213879649d41900e95f515d8685c3870c935358bcb25567b2f6f332301e1ad88188056047b7b
2025-04-15 13:20:09 +00:00
Tobin C. Harding 53837d9a2e
units: Improve crate level docs
Add a bit more to the crate level docs. This is a simple crate so we
don't need all that much.

Done for: C-CRATE-DOC
2025-04-14 14:33:26 +10:00
Tobin C. Harding 0361604bab
Add impls for NumOpResult div and mul
We recently added div and mul for combinations of `Amount`, `FeeRate`,
and `Weight`. When doing so we forgot to add variations for
`NumOpResult`.
2025-04-14 11:32:24 +10:00
Tobin C. Harding 0f62c9a582
units: Make minor improvements to MathOp
Follow up from #4312, improve the `MathOp` type by:

- Do not provide public constructor
- Add cast protection
2025-04-14 10:37:28 +10:00
Jamil Lambert, PhD ec38860b65
Add a test to kill mutants in MathOp
Weekly mutation testing found mutants in `is_overflow` and
`is_divide_by_zero`.

Add a test to kill them.
2025-04-11 09:31:13 +01:00
merge-script c5b1b31963
Merge rust-bitcoin/rust-bitcoin#4320: units: Do trivial docs fixes
da69e636a9 units: Use 100 column width in rustdoc comments (Tobin C. Harding)
53c6ae4d40 units: Remove expect from rustdoc example (Tobin C. Harding)

Pull request description:

  A couple of quick docs fixes while trying to polish `units`.

ACKs for top commit:
  apoelstra:
    ACK da69e636a9d21e602289062279ed5ebc6b1429b6; successfully ran local tests

Tree-SHA512: acfbec90b0327850b882c5e1b1e7eaadbf0a09a30dcc46529386ea419ed74846a678a5980f5706f8d280f30ec6f6d06af2db8f0e1748523b15ad47a654caee4b
2025-04-10 20:54:11 +00:00
Tobin C. Harding da69e636a9
units: Use 100 column width in rustdoc comments
We typically use 100 column width for comments, do so but only if it
does not make the layout worse.
2025-04-08 14:25:04 +10:00
Tobin C. Harding 53c6ae4d40
units: Remove expect from rustdoc example
We can just assert against an explicit `Some` value instead of using
`expect`.
2025-04-08 14:25:04 +10:00
Tobin C. Harding d6881ff5f8
units: Enable differentiating div-by-zero
Division by zero is a different error class that overflow. Add a
`MathOp` enum that enables one to check the error class.
2025-04-08 09:04:30 +10:00
Tobin C. Harding 5fb64953c5
units: Return NumOpResult when implementing Div
Currently we use a std numeric type for the output of various `Div`
implementations while other ops use `NumOpResult`. This makes it
difficult to chain operations.

Throughout the crate use `Output = NumOpResult<Foo>` when implementing
`Div`.

Later we want to enable users differentiating between an overflow and a
div-by-zero. Explicitly do not implement that yet, done separately to
assist review.
2025-04-07 15:08:01 +10:00
Tobin C. Harding dba61c9efe
units: Fix internal docs
The `impl_op_for_references` macro implements an `ops` trait, nothing to
do with opcodes.
2025-04-07 12:14:12 +10:00
Tobin C. Harding 512326b8b9
units: Macroize implementing OptionExt
We are going to add implementations of `OptionExt` for various other
types and all impls are almost identical. To make doing so easier
macroize the implementation for `Amount` and `SignedAmount`.

Internal change only, no logic changes.
2025-04-07 12:14:12 +10:00
Tobin C. Harding f5b54e5fe0
units: Move general result stuff to a separate module
We currently use the `NumOpResult` for operations involving more than
just amount types (e.g. `FeeRate`) however when the `result` module was
written we only used amount types.

To make the intention of the custom result types more clear introduce a
top level `result` module and move the general code there. Leave the
amount implementations in the `amount` module. Note that both `result`
modules are private.

Move the `OptionExt` impls because later we will add a bunch more of them.

Internal change only, no logic changes.
2025-04-07 12:14:09 +10:00
Tobin C. Harding f49efdf3f7
units: Remove mention of amount in result module
We currently use the `NumOpResult` for operations involving more than
just amount types (e.g. `FeeRate`) however when the `result` module was
written we only used amount types.

To make the docs and code clearer use 'numeric type' instead of
'amount' in docs. And for local variables use `x` instead of `amount`.

This is docs and internal changes only.
2025-04-07 12:13:45 +10:00
Tobin C. Harding ca6c607953
Adhere to sanity rules for amount types
From my reading of the new sanity rules (#4090) we should only have a
single constructor that accesses the inner field of the amount types.

Furthermore we have one const constructor inside the privacy boundry and
a couple outside.

Move the const constructors outside of the privacy boundry.

Internal change only.

Please note

The function being inside privacy boundary allows it to not have the
"runtime" check (most likely optimized-away after inlining). But if we
wanted to get rid of that check we should have _unchecked method
instead. But we don't want that (yet), since the check here will have
zero performance impact in optimized builds and it's not worth the
cost of dealing with unchecked constructors to optimize debug builds.
2025-04-03 13:09:40 +11:00
Tobin C. Harding 6c614d9320
units: Fix panic message
Recently I wrote a panic message that included the maximum value of an
integer however I used the max of a 16 bit value for both signed and
unsigned - this is incorrect.

Use the correct values for `u16::MAX` and `i16::MAX`.
2025-04-03 12:58:30 +11:00
merge-script 59524adafd
Merge rust-bitcoin/rust-bitcoin#4295: Automated nightly rustfmt (2025-03-30)
b8910e201e 2025-03-30 automated rustfmt nightly (Fmt Bot)

Pull request description:

  Automated nightly `rustfmt` changes by [create-pull-request](https://github.com/peter-evans/create-pull-request) GitHub action

ACKs for top commit:
  apoelstra:
    ACK b8910e201ea4374bb0508aa50c6779d080ef6484; successfully ran local tests

Tree-SHA512: 9bd89439304322d30e04aae8f9803f9e07830b616cb49339ac4b1e0ee1bfe440865d9ebc7f41eea1bcd35cb751060215eec20d258d88e9f20dd3f905b9ab690f
2025-03-30 19:37:31 +00:00
merge-script f2869ad348
Merge rust-bitcoin/rust-bitcoin#4292: chore: fix grammatical errors
6ebdf61e76 Fix grammatical typos (VolodymyrBg)

Pull request description:

  base58/src/error.rs:

  - Corrected grammar in error comment: "Found a invalid ASCII byte" → "Found an invalid ASCII byte".

  bitcoin/CHANGELOG.md:

  - Fixed typo in function name: p2wpkh_signiture_hash → p2wpkh_signature_hash.

  units/src/amount/error.rs:

  - Fixed grammar: "was large than" → "was larger than".

  units/src/fee_rate/mod.rs:

  - Corrected typo: "assoctiated" → "associated".

  units/tests/api.rs:

  - Grammar fix: "THE POINT of tests are" → "THE POINT of tests is".

ACKs for top commit:
  apoelstra:
    ACK 6ebdf61e769903da1ad21fd6ab9bf22ff3c04bab; successfully ran local tests

Tree-SHA512: bb5800b6248bedad46d511a0123c50b1d8d2deacfa752cd675d21e40cb78a6a5d917da28a9a87c3f779cd13819d5b16a7668d1e388d1d58d200ea688d8c114ac
2025-03-30 15:19:49 +00:00
Fmt Bot b8910e201e 2025-03-30 automated rustfmt nightly 2025-03-30 01:27:51 +00:00
lfgtwo 89d61304af chore: remove needless question mark 2025-03-29 01:00:06 +08:00
merge-script 171c779c01
Merge rust-bitcoin/rust-bitcoin#4287: units: Kill mutants found in weekly mutation testing
f15e461baf Add an exclusion for a mutant in a deprecated fn (Jamil Lambert, PhD)
9a2b56f381 Modify test in Amount to kill mutants (Jamil Lambert, PhD)
1d1cf00b1e Add test to BlockTime to kill mutants (Jamil Lambert, PhD)

Pull request description:

  Weekly mutation testing found mutants in `Amount` and `BlockTime`.

  Add a test to `BlockTime`.
  Add two asserts to `Amount` tests.
  Exclude deprecated function from mutation testing.

  Closes #4225, #4243, #4278

ACKs for top commit:
  apoelstra:
    ACK f15e461baf463da0bf9d89018180c1d5032106c1; successfully ran local tests

Tree-SHA512: 18a405362db1b2eabac7c7ac01a56d306a1bf5f705626b5c217ec329e6420daa2f2e62b37c72537f29b7ee76b9fd795adde2da71b226fec3a74d0f25dca6cd96
2025-03-28 12:29:14 +00:00
VolodymyrBg 6ebdf61e76 Fix grammatical typos
Fix grammar and typos in documentation and README
2025-03-27 20:49:19 +02:00
merge-script 158240c3c9
Merge rust-bitcoin/rust-bitcoin#4284: Use `path = [bala]` for `rust-bitcoin`'s workspace members dependencies. remove `[patch.crates-io.balab]`
9a572dabde refactor: use path dependencies for workspace members in bitcoin/Cargo.toml (Eval EXEC)

Pull request description:

  This PR want to:

  1. make all workspace members use `workspace = true` syntax to import dependencies.
  2. use `path = [balabala]` to define dependencies, instead of useing `[patch.crates-io.balabala]` , fix: https://github.com/rust-bitcoin/rust-bitcoin/issues/4283

ACKs for top commit:
  Kixunil:
    ACK 9a572dabde
  apoelstra:
    ACK 9a572dabdeb077f96b2ab66be1a80fcec3e805e3; successfully ran local tests

Tree-SHA512: 834ef881ed3fd324a9ecca440e8e591984a7e474eb6aeab86a0301cbd08b6dc96ecdc34b306ad146b11b50f7488024c289b8f8c7c6de1a2bdba7aec515b722ee
2025-03-27 15:01:47 +00:00
Eval EXEC 9a572dabde
refactor: use path dependencies for workspace members in bitcoin/Cargo.toml
Signed-off-by: Eval EXEC <execvy@gmail.com>
2025-03-27 12:55:16 +08:00
Jamil Lambert, PhD 9a2b56f381
Modify test in Amount to kill mutants
Mutants found in weekly mutation testing.

Add an assert for both signed and unsigned to an existing test to kill
them.
2025-03-26 09:48:21 +00:00
Jamil Lambert, PhD 1d1cf00b1e
Add test to BlockTime to kill mutants
Mutants found in weekly mutation testing.

Add a test to kill them.
2025-03-26 09:36:42 +00:00
merge-script ecffb4071b
Merge rust-bitcoin/rust-bitcoin#4169: units: Increase ops impls in `block` module
3ae21d5111 Use impl_add/sub_assign for block interval (Tobin C. Harding)
9d55922952 Use impl_op_for_references for block height/interval (Tobin C. Harding)
f5e17914b6 Move Assign impls together (Tobin C. Harding)
cc66838e80 units: Remove unnecessary code comments (Tobin C. Harding)

Pull request description:

  Improve the ops impls in the `block` module using the already present macros.

ACKs for top commit:
  apoelstra:
    ACK 3ae21d5111444f5e01f6cfb1a2b9b314f66418a3; successfully ran local tests; nice!

Tree-SHA512: 6565426a06bb47d337d21cf5c59acca43e69228dbec8319fc95373025d220d8ec6273c54f214f312c4229603c455d08e4c6a8c108663c6db5086df36266979de
2025-03-26 02:21:12 +00:00
merge-script cf79f05ad6
Merge rust-bitcoin/rust-bitcoin#4271: Make code style consistent and fix naming in macro Array implementations
e744347022 Make usage of Self and type uniform across both modules (Erick Cestari)
dfb49f014c Rename impl_try_from_array to impl_from_array (Erick Cestari)

Pull request description:

  This PR makes two main changes:

  1. Standardizes the function signatures in the `Amount` and `SignedAmount` implementations by consistently using `Self` as the return type instead of the concrete type names. This improves code consistency, maintainability, and follows Rust's idiomatic practices.
  2. Renames `impl_try_from_array` to `impl_from_array` to better reflect its functionality.

  ### Changes
  **Consistent usage of Self instead of concrete types**

  - Replace all occurrences of `-> Amount` with `-> Self `in unsigned.rs
  - Replace all occurrences of `-> SignedAmount` with `-> Self` in signed.rs
  - Make similar replacements for Option/Result return types
  - Use `Self::` instead of explicit type name for static method calls

  **Function rename**

  Renamed `impl_try_from_array` to `impl_from_array` for better clarity

  ### Related Issues

  Closes #4210

  Closes #4241

ACKs for top commit:
  Kixunil:
    ACK e744347022
  tcharding:
    ACK e744347022
  apoelstra:
    ACK e744347022d1ad1e0ca0a83ec9350501af08297b; successfully ran local tests

Tree-SHA512: 3113f3ccf595b298afe6b23514f1de790284df7fcb55a13658aabe3ef4fcea0e401b65b0a2c67ac18da87a1bcd247bd1f1484856fe03470b98dfa2614958a3bb
2025-03-25 19:39:23 +00:00
merge-script 4525fd3cad
Merge rust-bitcoin/rust-bitcoin#4263: docs: fix LICENSE link
d0bead6f94 docs: fix LICENCE link (jike)

Pull request description:

  ![image](https://github.com/user-attachments/assets/9c08a57e-e958-487f-ba9d-978bd6fde913)

ACKs for top commit:
  tcharding:
    ACK d0bead6f94
  Kixunil:
    ACK d0bead6f94

Tree-SHA512: 148ea7c35ca8872e314e12889cab325af6965f533abea062c49d03809d57de3b476a97d39e2ae4e0c8479da263b7959c9cf2409050e3888af33b308c022391b1
2025-03-24 19:10:56 +00:00
jike d0bead6f94 docs: fix LICENCE link 2025-03-23 11:41:07 +00:00
Erick Cestari e744347022 Make usage of Self and type uniform across both modules
This commit standardizes the function signatures in the Amount and SignedAmount
implementations by consistently using Self as the return type instead of the concrete
type names. This makes the code more consistent, easier to maintain, and follows Rust's
idiomatic practices.

Changes:

Replace all occurrences of -> Amount with -> Self in unsigned.rs
Replace all occurrences of -> SignedAmount with -> Self in signed.rs
Make similar replacements for Option/Result return types
Use Self:: instead of the explicit type name for static method calls
2025-03-21 14:26:35 -03:00
Andrew Poelstra 2958521117
amount: remove from_sat_unchecked
Turns out we don't even need this. It is only used in one place now and
we can just stick an .expect there.
2025-03-18 19:33:03 +00:00