[Proposal] Specify the endianness of a bits/bytes array

[collinc97]

💥 Proposal

This proposal depends on the implementation of #682

Feature

Following the implementation of .bits() and .bytes() syntax. We should provide additional syntax or helper methods to allow the developer to specify or change the endianness of an array of bits or bytes. By default, all bit and byte arrays are returned in little endian format.

At a minimum, we should support methods that specify big endian format for bits and bytes.

Proposed Syntax 1

From @acoglio in this comment

Deprecate .bits() .bytes().
Add .little_endian_bits(), .little_endian_bytes(). Add .big_endian_bits(), .big_endian_bytes().

let a: u8 = 1;
let b: [bool; 8] = a.little_endian_bits();
let c: [bool; 8] = a.big_endian_bits();

assert(b == [1, 0, 0, 0, 0, 0, 0, 0]);
assert(c == [0, 0, 0, 0, 0, 0, 0, 1]);

Proposed Syntax 2

Functionally same as above, but uses shorter method names similar to rust:

Deprecate .bits() .bytes().
Add .to_le_bits(), .to_le_bytes(). Add .to_be_bits(), .to_be_bytes().

let a: u8 = 1;
let b: [bool; 8] = a.to_le_bits();
let c: [bool; 8] = a.to_be_bits();

assert(b == [1, 0, 0, 0, 0, 0, 0, 0]);
assert(c == [0, 0, 0, 0, 0, 0, 0, 1]);

Proposed Syntax 3

I think it would be appropriate to have a method that reverses the endianness of a bit or byte array. This feature could be used in any context to reverse the elements of an array. I realize this is a more major feature add since we are now adding standard methods to the array datatype. This syntax could be supported in addition to adopting one of the above proposals.

Keep .bits() .bytes() methods. Add .reverse()

let a: u8 = 1;
let b: [bool; 8] = a.bits();
let c: [bool; 8] = a.reverse();

assert(b == [1, 0, 0, 0, 0, 0, 0, 0]);
assert(c == [0, 0, 0, 0, 0, 0, 0, 1]);

[acoglio]

My vote is for Proposal 1 or 2, because they are symmetric w.r.t. little vs. big endian.

But in all three cases, I think that an operation to reverse arrays is of broader and independent interest and use.

[gluax]

My vote is option 2, writing a few less characters and the function name is still clear. Although a reverse method is definitely something we should consider adding at some point as well.

[gluax]

Blocked by #975.

[acoglio]

As discussed offline and on Slack, the fastest way to provide this capability in an initial and usable form is probably via natively implemented global functions

to/from-bits/bytes-le/be(<expression>)

in the same way as the BLAKE2s function works. This should be doable without doing #975 first.

Then, once #975 is done, we can add member functions

<expression>.to/from-bits/bytes/le/be()

with the same functionality, and deprecate, and later eliminate, the global functions.