mirrors/Nim
1
0
Fork 0
mirror of https://github.com/nim-lang/Nim.git synced 2026-01-10 06:54:16 +00:00
Code Issues Packages Projects Releases Wiki Activity

Improve endians module (#17674)

Browse Source 
Extend documentation
Add runnableExamples
This commit is contained in:
konsumlamm
2021-04-08 14:08:58 +02:00
committed by GitHub
parent 643dbc743b
commit 1b03accac7
1 changed files with 42 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
lib/pure/endians.nim
View File

@@ -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.