Improve endians module (#17674)

Extend documentation
Add runnableExamples

lib/pure/endians.nim

@@ -10,6 +10,11 @@
 ## This module contains helpers that deal with different byte orders
 ## (`endian`:idx:).
 ##
+## Endianess is the order of bytes of a value in memory. Big-endian means that
+## the most significant byte is stored at the smallest memory address,
+## while little endian means that the least-significant byte is stored
+## at the smallest address. See also https://en.wikipedia.org/wiki/Endianness.
+##
 ## Unstable API.
 
 when defined(gcc) or defined(llvm_gcc) or defined(clang):
@@ -47,7 +52,7 @@ else:
 
 when useBuiltinSwap:
   template swapOpImpl(T: typedesc, op: untyped) =
-    ## We have to use `copyMem` here instead of a simple deference because they
+    ## We have to use `copyMem` here instead of a simple dereference because they
     ## may point to a unaligned address. A sufficiently smart compiler _should_
     ## be able to elide them when they're not necessary.
     var tmp: T
@@ -56,18 +61,40 @@ when useBuiltinSwap:
     copyMem(outp, addr tmp, sizeof(T))
 
   proc swapEndian64*(outp, inp: pointer) {.inline, noSideEffect.} =
+    ## Copies `inp` to `outp`, reversing the byte order.
+    ## Both buffers are supposed to contain at least 8 bytes.
+    runnableExamples:
+      var a = [1'u8, 2, 3, 4, 5, 6, 7, 8]
+      var b: array[8, uint8]
+      swapEndian64(addr b, addr a)
+      assert b == [8'u8, 7, 6, 5, 4, 3, 2, 1]
+
     swapOpImpl(uint64, builtin_bswap64)
 
   proc swapEndian32*(outp, inp: pointer) {.inline, noSideEffect.} =
+    ## Copies `inp` to `outp`, reversing the byte order.
+    ## Both buffers are supposed to contain at least 4 bytes.
+    runnableExamples:
+      var a = [1'u8, 2, 3, 4]
+      var b: array[4, uint8]
+      swapEndian32(addr b, addr a)
+      assert b == [4'u8, 3, 2, 1]
+
     swapOpImpl(uint32, builtin_bswap32)
 
   proc swapEndian16*(outp, inp: pointer) {.inline, noSideEffect.} =
+    ## Copies `inp` to `outp`, reversing the byte order.
+    ## Both buffers are supposed to contain at least 2 bytes.
+    runnableExamples:
+      var a = [1'u8, 2]
+      var b: array[2, uint8]
+      swapEndian16(addr b, addr a)
+      assert b == [2'u8, 1]
+
     swapOpImpl(uint16, builtin_bswap16)
 
 else:
   proc swapEndian64*(outp, inp: pointer) =
-    ## copies `inp` to `outp` swapping bytes. Both buffers are supposed to
-    ## contain at least 8 bytes.
     var i = cast[cstring](inp)
     var o = cast[cstring](outp)
     o[0] = i[7]
@@ -80,8 +107,6 @@ else:
     o[7] = i[0]
 
   proc swapEndian32*(outp, inp: pointer) =
-    ## copies `inp` to `outp` swapping bytes. Both buffers are supposed to
-    ## contain at least 4 bytes.
     var i = cast[cstring](inp)
     var o = cast[cstring](outp)
     o[0] = i[3]
@@ -90,8 +115,6 @@ else:
     o[3] = i[0]
 
   proc swapEndian16*(outp, inp: pointer) =
-    ## copies `inp` to `outp` swapping bytes. Both buffers are supposed to
-    ## contain at least 2 bytes.
     var i = cast[cstring](inp)
     var o = cast[cstring](outp)
     o[0] = i[1]
@@ -106,8 +129,20 @@ when system.cpuEndian == bigEndian:
   proc bigEndian16*(outp, inp: pointer) {.inline.} = copyMem(outp, inp, 2)
 else:
   proc littleEndian64*(outp, inp: pointer) {.inline.} = copyMem(outp, inp, 8)
+    ## Copies `inp` to `outp`, storing it in 64-bit little-endian order.
+    ## Both buffers are supposed to contain at least 8 bytes.
   proc littleEndian32*(outp, inp: pointer) {.inline.} = copyMem(outp, inp, 4)
+    ## Copies `inp` to `outp`, storing it in 32-bit little-endian order.
+    ## Both buffers are supposed to contain at least 4 bytes.
   proc littleEndian16*(outp, inp: pointer){.inline.} = copyMem(outp, inp, 2)
+    ## Copies `inp` to `outp`, storing it in 16-bit little-endian order.
+    ## Both buffers are supposed to contain at least 2 bytes.
   proc bigEndian64*(outp, inp: pointer) {.inline.} = swapEndian64(outp, inp)
+    ## Copies `inp` to `outp`, storing it in 64-bit big-endian order.
+    ## Both buffers are supposed to contain at least 8 bytes.
   proc bigEndian32*(outp, inp: pointer) {.inline.} = swapEndian32(outp, inp)
+    ## Copies `inp` to `outp`, storing it in 32-bit big-endian order.
+    ## Both buffers are supposed to contain at least 4 bytes.
   proc bigEndian16*(outp, inp: pointer) {.inline.} = swapEndian16(outp, inp)
+    ## Copies `inp` to `outp`, storing it in 16-bit big-endian order.
+    ## Both buffers are supposed to contain at least 2 bytes.