u64 module for stdlib about miden-vm HOT 3 CLOSED

Now that we have most of the above implemented, I've spent some time thinking about different variants of operations and their naming conventions. Specifically, I have a couple of thoughts:

1. We should probably adopt Rust convention for different variants of arithmetic operations. For examples: checked_add instead of our current add.
2. We should probably introduce variants for handling mixed types. For example, adding u64 value to a u32 value.

Regarding the first one, I think we should have 4 variants which work as follows:

• checked_ variant which makes sure the inputs are u64 values and that the result also fits into u64 value. This is actually the only variant which performs such checks.
• unchecked_ variant which doesn't check if the inputs or the result are u64 values, but otherwise behaves like the checked_ variant.
• wrapping_ variant which discards the overflow and doesn't check if the the inputs are u64 values.
• overflowing_ variant which preserves the overflow and doesn't check if the inputs are u64 values.

Regarding the second point, we could introduce special variants for dealing specifically with u32 values, and then for each of these, we could also have checked_, wrapping_ etc. variants. For example, add_u32_checked and mul_by_u32_checked. One open question here is how to deal with the fact that either left or the right operands could be be u32 values. Should we have a separate procedure for each? Or should we assume that u32 value is always in the right operand (this is not too difficult to work with for addition and multiplication, but not quite sure how it will work for subtraction and division).

u64 module procedures

To list out all procedures I could think of for the u64 stdlib module (for now without the support for u32 operand handling):

• Addition
  • checked_add
  • wrapping_add
  • overflowing_add
• Subtraction
  • checked_sub
  • wrapping_sub
  • overflowing_sub
• Multiplication
  • checked_mul
  • wrapping_mul
  • overflowing_mul
• Division
  • checked_div - integer division, checks if the inputs are u64 values.
  • unchecked_div - integer division, does not check if the inputs are u64 values.
  • checked_mod - modulo operation, checks if the inputs are u64 values.
  • unchecked_mod - modulo operation, does not check if the inputs are u64 values.
  • checked_divmod - outputs both the quotient and the remainder, checks if the inputs are u64 values.
  • unchecked_divmod - outputs both the quotient and the remainder, does not check if the inputs are u64 values.
• Equality comparison
  • checked_eq
  • checked_neq
  • checked_eqz
  • unchecked_eq
  • unchecked_neq
  • unchecked_eqz
• Ordered comparisons
  • checked_lt
  • checked_lte
  • checked_gt
  • checked_gte
  • unchecked_lt
  • unchecked_lte
  • unchecked_gt
  • unchecked_gte
• Bit manipulation
  • checked_and
  • checked_or
  • checked_xor
  • checked_shl - checks if the input is a u64 value.
  • checked_shr - checks if the input is a u64 value.
  • checked_rotr - checks if the input is a u64 value.
  • checked_rotl - checks if the input is a u64 value.
  • unchecked_shl - checks if the input is a u64 value.
  • unchecked_shr - checks if the input is a u64 value.
  • unchecked_rotr - checks if the input is a u64 value.
  • unchecked_rotl - checks if the input is a u64 value.
  • overflowing_shl - keeps the "shifted out" bits in another u64, does not check if the input is a u64 value.
  • overflowing_shr- keeps the "shifted out" bits in another u64, does not check if the input is a u64 value.
• Other potential procedures
  • exp
  • min
  • max
  • log
  • log2

Any feedback on the naming convention as well as the actual procedures (missing or extraneous), is welcome.

from miden-vm.

I agree with this overall. I think following the Rust naming conventions makes sense and that having mixed operations for u64 and u32 would also be useful.

I have a couple of small points. Firstly, the shl/shr don't match what Rust offers, since wrapping_shl is missing and overflowing/checked are different. In Rust, it's the shift value which is checked. In our case, we may want to check both things. Also, their overflowing returns a bool rather than a shifted out value (which we may find useful). These differences are not necessarily a problem, but it may make it more confusing to be following the nomenclature without following the functionality so I figured it's at least worth discussion. (Also, the notes for the unchecked shift/rotate ops seem to be wrong.)

Regarding the second point, we could introduce special variants for dealing specifically with u32 values, and then for each of these, we could also have checked_, wrapping_ etc. variants. For example, add_u32_checked and mul_by_u32_checked

I think we should keep the order of the wording similar to the others, so I would prefer something like checked_u32_add and checked_u32_mul.

One open question here is how to deal with the fact that either left or the right operands could be be u32 values.

I'm undecided on this, but if we want to support both options for div & sub then we should probably do it for add/mul as well. So I guess the question is if we want to support u32 - u64

from miden-vm.

Mostly closed by #159 and other PRs. I'll create stand-alone issues for the few remaining items.

from miden-vm.