# Endian-ness

The unit at [mem/endian.fs] contain words as well as Big Moustache actions and
custom values [lib/bm] to read 32-bit or 16-bit values in arbitrary endian-ness
regardless of host's endian-ness. This unit is also exposed to C through
[mem/endian.h].

Two endian-ness are supported, little-endian (LE) and big endian (BE). Let's
consider this memory arrangement:

A+0  A+1  A+2  A+3
$12  $34  $56  $78

This memory can be read as little endian, that is, the least significant byte
first, with "le@ ( a -- n ). It reads as $78563412. It can also read as big
endian, that is, the most significant byte first, with "be@ ( a -- n )". It then
reads as $12345678. Same principle for writing.

Each of these words have a 16-bit variant, so they can be called with a "w"
prefix. They don't have a "c" one because it makes no sense.

Additionally, these words can ignore alignment discipline [doc/usage/mem]
because they are guaranteed to read and write byte by byte.

The tradeoff is that these words are slower than their native counterpart.

## Moustache actions

The four moustache actions provided by this unit are "le@", "le!", "be@" and
"be!". These actions are compile-only.

They are compatible with all modifiers except "!" and "&". Target sizes can be
1, 2, 3 (yes, 3! this makes this unit the most convenient way to do 24-bit
accesses) or 4 bytes. Doing 1 byte access is useless as the native "@" and "!"
will do a better job, but they're allowed nonetheless.

## Custom values

This unit also provides the "littleendian{}" and "bigendian{}" custom values,
which of course bind the "getters" to le@ and be@ and the setters to le! and
be!. Example usage:

  create data ,"FOO!"
  bigendian{'data} mystr
  mystr .x \ prints 464f4f21
  $42415221 to mystr
  data 4 rtype \ prints "BAR!"

## Preserves A registers

All words in this unit preserve the A register (see [doc/hal]).

## API

be@        a -- n        *B* Big-endian fetch
be!        n a --        *B* Big-endian store
be,        n --          *B* Big-endian write
le@        a -- n        *B* Little-endian fetch
le!        n a --        *B* Little-endian store
le,        n --          *B* Little-endian write
