Computer architectures differ in how they store multi-byte integers in memory. The two primary methods are little-endian and big-endian. Little-endian ordering stores the least significant byte ("little end") at the lowest memory address, whereas big-endian ordering stores the most significant byte ("big end") first.
Data interoperability issues may arise when exchanging information between different architectures. For example, the USB Protocol specification defines data records in little-endian format, while the SCSI Protocol utilizes the big-endian convention.
The Standard Library facilitates flexible conversion between these formats via a set of macros. These macros convert data from a specified format to the CPU's native format and vice versa. There are four categories of conversion macros:
- stCPUToLE* - Converts CPU-native format to little-endian.
- stCPUToBE* - Converts CPU-native format to big-endian.
- stLEToCPU* - Converts little-endian format to CPU-native format.
- stBEToCPU* - Converts big-endian format to CPU-native format.
(*) Represents the data width in bits (16, 32, or 64). 64-bit support is available only when AR_USE_64_BIT is set to 1.
These macros optimize the process by performing operations only when the target architecture differs from the host. For example, if stLEToCPU32 is used on a processor already operating in little-endian mode, it resolves to a simple value assignment.
By default, the library is configured for little-endian processors. Including the correct architecture specific files should automatically adapt the library to the platform. If manual configuration is required, set AR_LENDIAN_CPU to 1 for little-endian mode, or to 0 for big-endian mode.
The auxiliary function stIsLEndianCPU allows for runtime verification of the processor's endianness. This function is excluded from compilation by default; to enable it, set ST_IS_LENDIAN_CPU_FUNC to 1.
If endianness conversion is not required (e.g., when utilizing a single architecture), this module can be excluded from compilation to reduce code size by setting ST_USE_ENDIANS to 0.