math: update documentation (#14457)

vlib/math/unsigned/uint256.v

@@ -14,26 +14,32 @@ pub mut:
 	hi Uint128 = uint128_zero // upper 128 bit half
 }
 
+// uint256_from_128 creates a new `unsigned.Uint256` from the given Uint128 value
 pub fn uint256_from_128(v Uint128) Uint256 {
 	return Uint256{v, uint128_zero}
 }
 
+// uint256_from_64 creates a new `unsigned.Uint256` from the given u64 value
 pub fn uint256_from_64(v u64) Uint256 {
 	return uint256_from_128(uint128_from_64(v))
 }
 
+// is_zero checks if specified Uint256 is zero
 pub fn (u Uint256) is_zero() bool {
 	return u.lo.is_zero() && u.hi.is_zero()
 }
 
+// equals checks if the two Uint256 values match one another
 pub fn (u Uint256) equals(v Uint256) bool {
 	return u.lo.equals(v.lo) && u.hi.equals(v.hi)
 }
 
-pub fn (u Uint256) euqals_128(v Uint128) bool {
+// equals_128 checks if the Uint256 value matches the Uint128 value
+pub fn (u Uint256) equals_128(v Uint128) bool {
 	return u.lo.equals(v) && u.hi.is_zero()
 }
 
+// cmp returns 1 if u is greater than v, -1 if u is less than v, or 0 if equal
 pub fn (u Uint256) cmp(v Uint256) int {
 	h := u.hi.cmp(v.hi)
 	if h != 0 {
@@ -42,6 +48,7 @@ pub fn (u Uint256) cmp(v Uint256) int {
 	return u.lo.cmp(v.lo)
 }
 
+// cmp_128 returns 1 if u is greater than v (Uint128), -1 if u is less than v, or 0 if equal
 pub fn (u Uint256) cmp_128(v Uint128) int {
 	if !u.hi.is_zero() {
 		return 1
@@ -49,34 +56,42 @@ pub fn (u Uint256) cmp_128(v Uint128) int {
 	return u.lo.cmp(v)
 }
 
+// not returns a binary negation of the Uint256 value
 pub fn (u Uint256) not() Uint256 {
 	return Uint256{u.lo.not(), u.hi.not()}
 }
 
+// and returns a Uint256 value that is the bitwise and of u and v
 pub fn (u Uint256) and(v Uint256) Uint256 {
 	return Uint256{u.lo.and(v.lo), u.hi.and(v.hi)}
 }
 
+// and_128 returns a Uint256 value that is the bitwise and of u and v, which is a Uint128
 pub fn (u Uint256) and_128(v Uint128) Uint256 {
 	return Uint256{u.lo.and(v), uint128_zero}
 }
 
+// or_ returns a Uint256 value that is the bitwise or of u and v
 pub fn (u Uint256) or_(v Uint256) Uint256 {
 	return Uint256{u.lo.or_(v.lo), u.hi.or_(v.hi)}
 }
 
+// or_128 returns a Uint256 value that is the bitwise or of u and v, which is a Uint128
 pub fn (u Uint256) or_128(v Uint128) Uint256 {
 	return Uint256{u.lo.or_(v), u.hi}
 }
 
+// xor returns a Uint256 value that is the bitwise xor of u and v
 pub fn (u Uint256) xor(v Uint256) Uint256 {
 	return Uint256{u.lo.xor(v.lo), u.hi.xor(v.hi)}
 }
 
+// xor_128 returns a Uint256 value that is the bitwise xor of u and v, which is a Uint128
 pub fn (u Uint256) xor_128(v Uint128) Uint256 {
 	return Uint256{u.lo.xor(v), u.hi}
 }
 
+// add_256 - untested
 pub fn add_256(x Uint256, y Uint256, carry u64) (Uint256, u64) {
 	mut sum := Uint256{}
 	mut carry_out := u64(0)
@@ -85,6 +100,7 @@ pub fn add_256(x Uint256, y Uint256, carry u64) (Uint256, u64) {
 	return sum, carry_out
 }
 
+// sub_256 - untested
 pub fn sub_256(x Uint256, y Uint256, borrow u64) (Uint256, u64) {
 	mut diff := Uint256{}
 	mut borrow_out := u64(0)
@@ -93,6 +109,7 @@ pub fn sub_256(x Uint256, y Uint256, borrow u64) (Uint256, u64) {
 	return diff, borrow_out
 }
 
+// mul_256 - untested
 pub fn mul_256(x Uint256, y Uint256) (Uint256, Uint256) {
 	mut hi := Uint256{}
 	mut lo := Uint256{}
@@ -114,31 +131,37 @@ pub fn mul_256(x Uint256, y Uint256) (Uint256, Uint256) {
 	return hi, lo
 }
 
+// add returns a Uint256 that is equal to u+v
 pub fn (u Uint256) add(v Uint256) Uint256 {
 	sum, _ := add_256(u, v, 0)
 	return sum
 }
 
+// overflowing_add - untested
 pub fn (u Uint256) overflowing_add(v Uint256) (Uint256, u64) {
 	sum, overflow := add_256(u, v, 0)
 	return sum, overflow
 }
 
+// add_128 returns a Uint256 that is equal to u+v, v being a Uint128
 pub fn (u Uint256) add_128(v Uint128) Uint256 {
 	lo, c0 := add_128(u.lo, v, 0)
 	return Uint256{lo, u.hi.add_64(c0)}
 }
 
+// sub returns a Uint256 that is equal to u-v
 pub fn (u Uint256) sub(v Uint256) Uint256 {
 	diff, _ := sub_256(u, v, 0)
 	return diff
 }
 
+// sub_128 returns a Uint256 that is equal to u-v, v being a Uint128
 pub fn (u Uint256) sub_128(v Uint128) Uint256 {
 	lo, b0 := sub_128(u.lo, v, 0)
 	return Uint256{lo, u.hi.sub_64(b0)}
 }
 
+// mul returns a Uint256 that is eqal to u*v
 pub fn (u Uint256) mul(v Uint256) Uint256 {
 	mut hi, mut lo := mul_128(u.lo, v.lo)
 	hi = hi.add(u.hi.mul(v.lo))
@@ -146,11 +169,13 @@ pub fn (u Uint256) mul(v Uint256) Uint256 {
 	return Uint256{lo, hi}
 }
 
+// mul_128 returns a Uint256 that is eqal to u*v, v being a Uint128
 pub fn (u Uint256) mul_128(v Uint128) Uint256 {
 	hi, lo := mul_128(u.lo, v)
 	return Uint256{lo, hi.add(u.hi.mul(v))}
 }
 
+// quo_rem - untested
 pub fn (u Uint256) quo_rem(v Uint256) (Uint256, Uint256) {
 	if v.hi.is_zero() {
 		q, r := u.quo_rem_128(v.lo)
@@ -173,6 +198,7 @@ pub fn (u Uint256) quo_rem(v Uint256) (Uint256, Uint256) {
 	return q, r
 }
 
+// quo_rem_128 - untested
 pub fn (u Uint256) quo_rem_128(v Uint128) (Uint256, Uint128) {
 	if u.hi.cmp(v) < 0 {
 		lo, r := div_128(u.hi, u.lo, v)
@@ -184,6 +210,7 @@ pub fn (u Uint256) quo_rem_128(v Uint128) (Uint256, Uint128) {
 	return Uint256{lo, hi}, r2
 }
 
+// quo_rem_64 - untested
 pub fn (u Uint256) quo_rem_64(v u64) (Uint256, u64) {
 	mut q := Uint256{}
 	mut r := u64(0)
@@ -192,6 +219,7 @@ pub fn (u Uint256) quo_rem_64(v u64) (Uint256, u64) {
 	return q, r
 }
 
+// rsh returns a new Uint256 that has been right bit shifted
 pub fn (u Uint256) rsh(n_ u32) Uint256 {
 	mut n := n_
 	if n > 128 {
@@ -205,6 +233,7 @@ pub fn (u Uint256) rsh(n_ u32) Uint256 {
 	return Uint256{Uint128{u.lo.lo >> n | u.lo.hi << (64 - n), u.lo.hi >> n | u.hi.lo << (64 - n)}, Uint128{u.hi.lo >> n | u.hi.hi << (64 - n), u.hi.hi >> n}}
 }
 
+// lsh returns a new Uint256 that has been left bit shifted
 pub fn (u Uint256) lsh(n_ u32) Uint256 {
 	mut n := n_
 	if n > 128 {
@@ -219,36 +248,43 @@ pub fn (u Uint256) lsh(n_ u32) Uint256 {
 	return Uint256{Uint128{u.lo.lo << n, u.lo.hi << n | u.lo.lo >> (64 - n)}, Uint128{u.hi.lo << n | u.lo.hi >> (64 - n), u.hi.hi << n | u.hi.lo >> (64 - n)}}
 }
 
+// div - untested
 pub fn (u Uint256) div(v Uint256) Uint256 {
 	q, _ := u.quo_rem(v)
 	return q
 }
 
+// div_128 - untested
 pub fn (u Uint256) div_128(v Uint128) Uint256 {
 	q, _ := u.quo_rem_128(v)
 	return q
 }
 
+// div_64 - untested
 pub fn (u Uint256) div_64(v u64) Uint256 {
 	q, _ := u.quo_rem_64(v)
 	return q
 }
 
+// mod - untested
 pub fn (u Uint256) mod(v Uint256) Uint256 {
 	_, r := u.quo_rem(v)
 	return r
 }
 
+// mod_128 - untested
 pub fn (u Uint256) mod_128(v Uint128) Uint128 {
 	_, r := u.quo_rem_128(v)
 	return r
 }
 
+// mod_64 - untested
 pub fn (u Uint256) mod_64(v u64) u64 {
 	_, r := u.quo_rem_64(v)
 	return r
 }
 
+// rotate_left returns a new Uint256 that has been left bit shifted
 pub fn (u Uint256) rotate_left(k int) Uint256 {
 	mut n := u32(k) & 255
 	if n < 64 {
@@ -283,10 +319,12 @@ pub fn (u Uint256) rotate_left(k int) Uint256 {
 	return Uint256{Uint128{u.lo.hi << n | u.lo.lo >> (64 - n), u.hi.lo << n | u.lo.hi >> (64 - n)}, Uint128{u.hi.hi << n | u.hi.lo >> (64 - n), u.lo.lo << n | u.hi.hi >> (64 - n)}}
 }
 
+// rotate_right returns a new Uint256 that has been right bit shifted
 pub fn (u Uint256) rotate_right(k int) Uint256 {
 	return u.rotate_left(-k)
 }
 
+// len returns the length of the binary value without the leading zeros
 pub fn (u Uint256) len() int {
 	if !u.hi.is_zero() {
 		return 128 + u.hi.len()
@@ -294,6 +332,7 @@ pub fn (u Uint256) len() int {
 	return u.lo.len()
 }
 
+// leading_zeros returns the number of 0s at the beginning of the binary value of the Uint256 value [0, 256]
 pub fn (u Uint256) leading_zeros() int {
 	if !u.hi.is_zero() {
 		return u.hi.leading_zeros()
@@ -301,6 +340,7 @@ pub fn (u Uint256) leading_zeros() int {
 	return 128 + u.lo.leading_zeros()
 }
 
+// trailing_zeros returns the number of 0s at the end of the binary value of the Uint256 value [0,256]
 pub fn (u Uint256) trailing_zeros() int {
 	if !u.lo.is_zero() {
 		return u.lo.trailing_zeros()
@@ -309,10 +349,12 @@ pub fn (u Uint256) trailing_zeros() int {
 	return 128 + u.hi.trailing_zeros()
 }
 
+// ones_count returns the number of ones in the binary value of the Uint256 value
 pub fn (u Uint256) ones_count() int {
 	return u.lo.ones_count() + u.hi.ones_count()
 }
 
+// str returns the decimal representation of the unsigned integer
 pub fn (u_ Uint256) str() string {
 	mut u := u_
 	if u.hi.is_zero() {
@@ -339,6 +381,7 @@ pub fn (u_ Uint256) str() string {
 	return ''
 }
 
+// uint256_from_dec_str creates a new `unsigned.Uint256` from the given string if possible
 pub fn uint256_from_dec_str(value string) ?Uint256 {
 	mut res := unsigned.uint256_zero
 	for b_ in value.bytes() {