Capitalization / Naming of ioendian about chapel

[mppf]

FWIW, 👍 for endianness e.g. endianness.little. I think endian and endian.little is my 2nd favorite, in the event that we think endianness is too weird a word / to hard to type.

[mppf]

I really hope there aren't going to be any more systems that are neither little endian nor big endian, but the endianness enum (whatever it is called) can handle such a thing, while a bool cannot. (There are some historical systems that were mixed endian.)

[lydia-duncan]

I also recall the IO subteam discussing whether it should be an enum or not at the time (we just didn't talk as much about the name as we probably should have), so I'd be in favor of considering that question decided anyways

[bradcray]

My gut preference was more towards endian.[little|big|native] because it seemed closest to the English phrase "little endian" / "big endian". But a downside to that is that we currently have arguments named endian that would need to change. Arguably not a reason to avoid considering it, but definitely a hassle.

It also occurred to me that user-facing interfaces that take an endianness could potentially be changed to avoid the enm in favor of a bool, as in:

proc foo(args...) { } // this would be the native endian overload
proc foo(args..., littleEndian: bool) { }  // this version would let people choose big vs. little

but that has the downside of resulting in less self-documenting interfaces (unless using the keyword-based argument passing), and may very well have been discussed and dismissed in conversations I wasn't a part of (or have forgotten).

[ShreyasKhandekar]

Planning to ask the team about this topic today

What is the API being presented?

ioendian is an enum that lets the user device the endian-ness of binary data while reading or writing it.
The options are to choose from 'big', 'little', and 'native'

How is it intended to be used?

It is used as an argument to the fileWriter and fileReader types to determine the byte order as described above.
Ex:

f.reader().readBinary(i, ioendian.big);

It is used in the binarySerializers and deserializers and as a result in almost all serializers that use that interface.

Uses in Arkouda

3 uses as part of the binarySerializer and deserializer interface, all localized in
https://github.com/Bears-R-Us/arkouda/blob/d5925c02d2041b2697fe19de36673ee300437b65/src/compat/gt-131/ArkoudaIOCompat.chpl#L61

What's the history of the feature

This enum was introduced when we deprecated binary conversions in format strings used in formatted IO in Feb 2022 in #19163. At that point we used format strings like

var i: int;
f.reader().readf("%>8i", i);

where the > meant that the data was read as if it was big-endian and < would mean little-endian

Brad brought up that this does not follow our naming conventions and didn't receive design attention regards to the name during it's inception.
Lydia noted that the question of using an enum vs bool for deciding endianness has already been decided by previous sub-teams.

Are there known GitHub issues with the feature?

Just this issue regarding the naming
#23868

What do other languages do?

a. Python

Python uses the >, <, = syntax to determine what endianness binary data is written or read as.
It is brought in by importing struct

Ex:

pack(">bhl", 1, 2, 3)

Which packs the stuff in big endian format as long ints.

We've moved away from binary format strings, so I doubt this is something we would want to take inspiration from.

However, python does have a way to check the byte order of the system that looks more relevant from a naming standpoint.
We can check the endianness of the system using sys.byteorder which returns either little or big based on the system.

b. C/C++

There isn't really a universal way to deal with endianness

C++ has the following two functions:

1. uint16_t htons(uint16_t hostshort) - converts host byte order to network byte order.
2. uint16_t ntohs(uint16_t hostshort) - converts network byte order to host byte order.

and users have their own functions usually that deal with checking endianness

c. Rust

Rust has a byteorder crate that is analogous to determine the endianness when reading and writing.
It uses two enums BigEndian and LittleEndian which support methods for different types

d. Swift

For it's Int, FixedWidthInteger, and Int8 types, Swift has littleEndian and bigEndian properties which give the respective representations of those types

e. Julia

Julia doesn't seem to have great ways to handle endianness and uses other functions like hton and ntoh or bswap like C++.

f. Go

Go provides the binary.byeOrder interface which is very similar to Rust in the sense that it provide two types that implement it binary.LittleEndian and binary.BigEndian

Are there features it is related to? What impact would changing or adding this feature have on those other features?

This would have a small impact on the binarySerializers and deserializers

How do you propose to solve the problem?

We have a bunch of different names that we can use for this enum along with what the elements of it would be called.

First up are the changes where only the name of the enum is changed and the elements remain the same.

1. Just fix the casing and call it ioEndian
2. endianness
3. endian

• This would require renaming some arguments, but not a big deal, just a hassle

4. endianKind
5. byteOrder

Finally we can also change the naming of the elements within it

6. byteOrder but the elements are nativeEndian, bigEndian, and littleEndian

Although most languages use "byte order" or some casing of that, I think endianness is my favorite.
If we want to align ourselves with other languages then option 6 might be what we want here.

[ShreyasKhandekar]

Just noting here that we got unanimous support (11 votes from the team) for endianness and that's what the new name is going to be.