Naming conventions for widening/split operations

[tarcieri]

There are two different conventions for widening operations used in this crate:

• widening_* as used by WideningMul::widening_mul and inherent methods
• *_wide as used by square_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?

[tarcieri]

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.

[andrewwhitehead]

I think related to this are the methods on BoxedUint, which currently implements a 'concatenating' multiplication and squaring as mul and square. concatenating_mul can (and probably should) be used through the ConcatenatingMul trait, but there isn't a corresponding ConcatenatingSquare trait. ConcatenatingMul could have a concatenating_square method though, even with a default implementation.

[tarcieri]

@andrewwhitehead that sounds fine to me

[andrewwhitehead]

I believe this can be closed