encoding.binary: add unit tests and module documentation (#15000)

.gitignore

@@ -105,3 +105,6 @@ thirdparty/stdatomic/nix/cpp/*.h
 
 # ignore VLS log
 vls.log
+
+# ignore v2go tmperror files
+*.tmperr

vlib/encoding/binary/README.md

@@ -0,0 +1,23 @@
+## Description
+
+`encoding.binary` contains utility functions for converting between an array of bytes (`[]u8`)
+and unsigned integers of various widths (`u16`, `u32`, and `u64`).
+
+There are two ways in which bytes can be encoded:
+
+1. Little endian: The least significant bytes are stored first, followed by the most
+   significant bytes.
+2. Big endian: The most significant bytes are stored first, opposite to the little endian
+   convention.
+
+For example, let us take the number `0x12345678`. In little endian, the bytes are extracted as
+`0x78`, `0x56`, `0x34`, and `0x12`. In big endian, the bytes are `0x12`, `0x34`, `0x56`,
+and `0x78`.
+
+We follow a similar procedure when we want to go the other way around. Consider the second
+sequence of bytes in the previous example: `0x12`, `0x34`, `0x56`, and `0x78`. If we encode
+this sequence in little endian format, we get the integer `0x78563412`. If we encode this
+sequence in big endian, we get `0x12345678`.
+
+**NOTE:** The functions in this module assume appropriately sized u8 arrays. If the sizes
+are not valid, the functions will panic.

vlib/encoding/binary/binary.v

@@ -3,26 +3,29 @@
 // that can be found in the LICENSE file.
 module binary
 
-// Little Endian
+// little_endian_u16 creates a u16 from two bytes in the array b in little endian order.
 [direct_array_access; inline]
 pub fn little_endian_u16(b []u8) u16 {
 	_ = b[1] // bounds check
 	return u16(b[0]) | (u16(b[1]) << u16(8))
 }
 
+// little_endian_put_u16 writes a u16 to the first two bytes in the array b in little endian order.
 [direct_array_access; inline]
 pub fn little_endian_put_u16(mut b []u8, v u16) {
 	_ = b[1] // bounds check
 	b[0] = u8(v)
 	b[1] = u8(v >> u16(8))
 }
 
+// little_endian_u32 creates a u32 from four bytes in the array b in little endian order.
 [direct_array_access; inline]
 pub fn little_endian_u32(b []u8) u32 {
 	_ = b[3] // bounds check
 	return u32(b[0]) | (u32(b[1]) << u32(8)) | (u32(b[2]) << u32(16)) | (u32(b[3]) << u32(24))
 }
 
+// little_endian_put_u32 writes a u32 to the first four bytes in the array b in little endian order.
 [direct_array_access; inline]
 pub fn little_endian_put_u32(mut b []u8, v u32) {
 	_ = b[3] // bounds check
@@ -32,12 +35,14 @@ pub fn little_endian_put_u32(mut b []u8, v u32) {
 	b[3] = u8(v >> u32(24))
 }
 
+// little_endian_u64 creates a u64 from eight bytes in the array b in little endian order.
 [direct_array_access; inline]
 pub fn little_endian_u64(b []u8) u64 {
 	_ = b[7] // bounds check
 	return u64(b[0]) | (u64(b[1]) << u64(8)) | (u64(b[2]) << u64(16)) | (u64(b[3]) << u64(24)) | (u64(b[4]) << u64(32)) | (u64(b[5]) << u64(40)) | (u64(b[6]) << u64(48)) | (u64(b[7]) << u64(56))
 }
 
+// little_endian_put_u64 writes a u64 to the first eight bytes in the array b in little endian order.
 [direct_array_access; inline]
 pub fn little_endian_put_u64(mut b []u8, v u64) {
 	_ = b[7] // bounds check
@@ -51,26 +56,29 @@ pub fn little_endian_put_u64(mut b []u8, v u64) {
 	b[7] = u8(v >> u64(56))
 }
 
-// Big Endian
+// big_endian_u16 creates a u16 from two bytes in the array b in big endian order.
 [direct_array_access; inline]
 pub fn big_endian_u16(b []u8) u16 {
 	_ = b[1] // bounds check
 	return u16(b[1]) | (u16(b[0]) << u16(8))
 }
 
+// big_endian_put_u16 writes a u16 to the first two bytes in the array b in big endian order.
 [direct_array_access; inline]
 pub fn big_endian_put_u16(mut b []u8, v u16) {
 	_ = b[1] // bounds check
 	b[0] = u8(v >> u16(8))
 	b[1] = u8(v)
 }
 
+// big_endian_u32 creates a u32 from four bytes in the array b in big endian order.
 [direct_array_access; inline]
 pub fn big_endian_u32(b []u8) u32 {
 	_ = b[3] // bounds check
 	return u32(b[3]) | (u32(b[2]) << u32(8)) | (u32(b[1]) << u32(16)) | (u32(b[0]) << u32(24))
 }
 
+// big_endian_put_u32 writes a u32 to the first four bytes in the array b in big endian order.
 [direct_array_access; inline]
 pub fn big_endian_put_u32(mut b []u8, v u32) {
 	_ = b[3] // bounds check
@@ -80,12 +88,14 @@ pub fn big_endian_put_u32(mut b []u8, v u32) {
 	b[3] = u8(v)
 }
 
+// big_endian_u64 creates a u64 from eight bytes in the array b in big endian order.
 [direct_array_access; inline]
 pub fn big_endian_u64(b []u8) u64 {
 	_ = b[7] // bounds check
 	return u64(b[7]) | (u64(b[6]) << u64(8)) | (u64(b[5]) << u64(16)) | (u64(b[4]) << u64(24)) | (u64(b[3]) << u64(32)) | (u64(b[2]) << u64(40)) | (u64(b[1]) << u64(48)) | (u64(b[0]) << u64(56))
 }
 
+// big_endian_put_u64 writes a u64 to the first eight bytes in the array b in big endian order.
 [direct_array_access; inline]
 pub fn big_endian_put_u64(mut b []u8, v u64) {
 	_ = b[7] // bounds check

vlib/encoding/binary/binary_test.v

@@ -0,0 +1,107 @@
+module binary
+
+// Little Endian Tests
+
+fn test_little_endian_u16() {
+	assert little_endian_u16([u8(0), 0]) == u16(0)
+	assert little_endian_u16([u8(5), 4]) == u16(0x0405)
+	assert little_endian_u16([u8(0x35), 0x57]) == u16(0x5735)
+	assert little_endian_u16([u8(0x35), 0x57]) != u16(0x3557)
+}
+
+fn test_little_endian_put_u16() {
+	mut buf := []u8{len: 2}
+	little_endian_put_u16(mut buf, 0x8725)
+	assert buf == [u8(0x25), 0x87]
+	little_endian_put_u16(mut buf, 0)
+	assert buf == [u8(0), 0]
+	little_endian_put_u16(mut buf, 0xfdff)
+	assert buf == [u8(0xff), 0xfd]
+}
+
+fn test_little_endian_u32() {
+	assert little_endian_u32([u8(0), 0, 0, 0]) == u32(0)
+	assert little_endian_u32([u8(5), 4, 9, 1]) == u32(0x01090405)
+	assert little_endian_u32([u8(0xf8), 0xa2, 0x9e, 0x21]) == u32(0x219ea2f8)
+	assert little_endian_u32([u8(0xf8), 0xa2, 0x9e, 0x21]) != u32(0xf8a29e21)
+}
+
+fn test_little_endian_put_u32() {
+	mut buf := []u8{len: 4}
+	little_endian_put_u32(mut buf, 0x872fea95)
+	assert buf == [u8(0x95), 0xea, 0x2f, 0x87]
+	little_endian_put_u32(mut buf, 0)
+	assert buf == [u8(0), 0, 0, 0]
+	little_endian_put_u32(mut buf, 0xfdf2e68f)
+	assert buf == [u8(0x8f), 0xe6, 0xf2, 0xfd]
+}
+
+fn test_little_endian_u64() {
+	assert little_endian_u64([u8(0), 0, 0, 0, 0, 0, 0, 0]) == u64(0)
+	assert little_endian_u64([u8(5), 4, 9, 1, 7, 3, 6, 8]) == u64(0x0806030701090405)
+	assert little_endian_u64([u8(0xf8), 0xa2, 0x9e, 0x21, 0x7f, 0x9f, 0x8e, 0x8f]) == u64(0x8f8e9f7f219ea2f8)
+	assert little_endian_u64([u8(0xf8), 0xa2, 0x9e, 0x21, 0x7f, 0x9f, 0x8e, 0x8f]) != u64(0xf8a29e217f9f8e8f)
+}
+
+fn test_little_endian_put_u64() {
+	mut buf := []u8{len: 8}
+	little_endian_put_u64(mut buf, 0x872fea95fdf2e68f)
+	assert buf == [u8(0x8f), 0xe6, 0xf2, 0xfd, 0x95, 0xea, 0x2f, 0x87]
+	little_endian_put_u64(mut buf, 0)
+	assert buf == [u8(0), 0, 0, 0, 0, 0, 0, 0]
+	little_endian_put_u64(mut buf, 0xfdf2e68f8e9f7f21)
+	assert buf == [u8(0x21), 0x7f, 0x9f, 0x8e, 0x8f, 0xe6, 0xf2, 0xfd]
+}
+
+// Big Endian Tests
+
+fn test_big_endian_u16() {
+	assert big_endian_u16([u8(0), 0]) == u16(0)
+	assert big_endian_u16([u8(5), 4]) == u16(0x0504)
+	assert big_endian_u16([u8(0x35), 0x57]) == u16(0x3557)
+	assert big_endian_u16([u8(0x35), 0x57]) != u16(0x5735)
+}
+
+fn test_big_endian_put_u16() {
+	mut buf := []u8{len: 2}
+	big_endian_put_u16(mut buf, 0x8725)
+	assert buf == [u8(0x87), 0x25]
+	big_endian_put_u16(mut buf, 0)
+	assert buf == [u8(0), 0]
+	big_endian_put_u16(mut buf, 0xfdff)
+	assert buf == [u8(0xfd), 0xff]
+}
+
+fn test_big_endian_u32() {
+	assert big_endian_u32([u8(0), 0, 0, 0]) == u32(0)
+	assert big_endian_u32([u8(5), 4, 9, 1]) == u32(0x05040901)
+	assert big_endian_u32([u8(0xf8), 0xa2, 0x9e, 0x21]) == u32(0xf8a29e21)
+	assert big_endian_u32([u8(0xf8), 0xa2, 0x9e, 0x21]) != u32(0x2192a2f8)
+}
+
+fn test_big_endian_put_u32() {
+	mut buf := []u8{len: 4}
+	big_endian_put_u32(mut buf, 0x872fea95)
+	assert buf == [u8(0x87), 0x2f, 0xea, 0x95]
+	big_endian_put_u32(mut buf, 0)
+	assert buf == [u8(0), 0, 0, 0]
+	big_endian_put_u32(mut buf, 0xfdf2e68f)
+	assert buf == [u8(0xfd), 0xf2, 0xe6, 0x8f]
+}
+
+fn test_big_endian_u64() {
+	assert big_endian_u64([u8(0), 0, 0, 0, 0, 0, 0, 0]) == u64(0)
+	assert big_endian_u64([u8(5), 4, 9, 1, 7, 3, 6, 8]) == u64(0x0504090107030608)
+	assert big_endian_u64([u8(0xf8), 0xa2, 0x9e, 0x21, 0x7f, 0x9f, 0x8e, 0x8f]) == u64(0xf8a29e217f9f8e8f)
+	assert big_endian_u64([u8(0xf8), 0xa2, 0x9e, 0x21, 0x7f, 0x9f, 0x8e, 0x8f]) != u64(0x8f8e9f7f219ea2f8)
+}
+
+fn test_big_endian_put_u64() {
+	mut buf := []u8{len: 8}
+	big_endian_put_u64(mut buf, 0x872fea95fdf2e68f)
+	assert buf == [u8(0x87), 0x2f, 0xea, 0x95, 0xfd, 0xf2, 0xe6, 0x8f]
+	big_endian_put_u64(mut buf, 0)
+	assert buf == [u8(0), 0, 0, 0, 0, 0, 0, 0]
+	big_endian_put_u64(mut buf, 0xfdf2e68f8e9f7f21)
+	assert buf == [u8(0xfd), 0xf2, 0xe6, 0x8f, 0x8e, 0x9f, 0x7f, 0x21]
+}