Naming conventions for widening/split operations
tarcieri opened this issue · 1 comments
There are two different conventions for widening operations used in this crate:
widening_*
as used byWideningMul::widening_mul
and inherent methods*_wide
as used bysquare_wide
,rem_wide
,overflowing_shl_*wide
Notably square_wide
returns a "split" result, rather than widening the output, which is called Uint::split_mul
for multiplication.
Should square_wide
be renamed to split_square
for consistency with split_mul
? Or should they be renamed to something else?
The proposed bigint helper methods in core (rust-lang/rust#85532) use the following names:
carrying_add
borrowing_sub
carrying_mul
widening_mul
Perhaps it would be good to generally align names and semantics with those. Names like adc
and sbb
that are derived from CPU instructions are on the one hand nicely terse and on the other perhaps a bit unclear unless you're already familiar with the CPU instructions.
They also use these type signatures:
/// `self + rhs + carry` (full adder)
fn carrying_add(self, rhs: Self, carry: bool) -> (Self, bool);
/// `self - rhs - carry` (full "subtractor")
fn borrowing_sub(self, rhs: Self, carry: bool) -> (Self, bool);
/// `self * rhs + carry` (multiply-accumulate)
fn carrying_mul(self, rhs: Self, carry: Self) -> (Self, Self);
/// `self * rhs` (wide multiplication, same as `self.carrying_mul(rhs, 0)`)
fn widening_mul(self, rhs: Self) -> (Self, Self);
Notably carrying_mul
and widening_mul
return a double-width result as two instances of Self
, which is what the latest prereleases of crypto-bigint
define as split_mul
.
So perhaps split_mul
should be renamed to widening_mul
, and the current widening_mul
should be renamed to something else.