Welcome to little lamb

Code » limb » commit 907342e

u32.h: Adjust doc/interfaces

author Olivier Brunel
2023-07-02 16:36:13 UTC
committer Olivier Brunel
2023-07-24 10:16:42 UTC
parent c7516477ba00df18aeea16f46d7092d6d042ca02

u32.h: Adjust doc/interfaces

src/doc/u32.h.0.md +38 -41
src/doc/u32.h/{u320_bfmt.3.md => u32_0bfmt.3.md} +0 -0
src/doc/u32.h/{u320_fmt.3.md => u32_0fmt.3.md} +0 -0
src/doc/u32.h/{u320_ofmt.3.md => u32_0fmtg.3.md} +0 -0
src/doc/u32.h/{u320_xfmt.3.md => u32_0ofmt.3.md} +0 -0
src/doc/u32.h/u32_0xfmt.3.md +1 -0
src/doc/u32.h/{u320_bscan.3.md => u32_bscan0.3.md} +0 -0
src/doc/u32.h/u32_fmt.3.md +17 -16
src/doc/u32.h/u32_le.3.md +13 -14
src/doc/u32.h/{u320_oscan.3.md => u32_oscan0.3.md} +0 -0
src/doc/u32.h/u32_pack.3.md +13 -11
src/doc/u32.h/u32_scan.3.md +17 -17
src/doc/u32.h/{u320_scan.3.md => u32_scan0.3.md} +0 -0
src/doc/u32.h/{u320_xscan.3.md => u32_xscan0.3.md} +0 -0
src/liblimb/include/limb/u32.h +9 -9

diff --git a/src/doc/u32.h.0.md b/src/doc/u32.h.0.md
index 9b12ebb..31df5ba 100644
--- a/src/doc/u32.h.0.md
+++ b/src/doc/u32.h.0.md
@@ -12,8 +12,6 @@ u32.h - 32bit unsigned integers
 # DESCRIPTION
 
 This header defines functions allowing to work with 32bit unsigned integers.
-It is mainly composed of macros to their `uint32_*` counterparts, offering
-slightly different interfaces.
 
 ## Constants
 
@@ -40,87 +38,86 @@ The following constants are defined :
 The following functions/macros are defined :
 
 : [u32_be](3)
-:: Same as [uint32_big](3)
+:: Convert a u32 number to big endian.
 
 : [u32_le](3)
-:: Same as [uint32_little](3)
+:: Convert a u32 number to little endian.
 
 : [u32p_be](3)
-:: Same as [uint32_bigp](3)
+:: Similar to [u32_be](3) but takes a pointer.
 
 : [u32p_le](3)
-:: Same as [uint32_littlep](3)
+:: Similar to [u32_le](3) but takes a pointer.
 
 : [u32pa_be](3)
-:: Same as [uint32_bign](3)
+:: Similar to [u32p_be](3) but for an array of pointers.
 
 : [u32pa_le](3)
-:: Same as [uint32_littlen](3)
+:: Similar to [u32p_le](3) but for an array of pointers.
 
 : [u32_pack](3)
-:: Same as [uint32_pack](3)
+:: Store a u32 number encoded in little endian.
 
 : [u32_unpack](3)
-:: Same as [uint32_unpack](3)
+:: Read a u32 number encoded in little endian.
 
 : [u32_pack_big](3)
-:: Same as [uint32_pack_big](3)
+:: Store a u32 number encoded in big endian.
 
 : [u32_unpack_big](3)
-:: Same as [uint32_unpack_big](3)
+:: Read a u32 number encoded in big endian.
 
 : [u32_fmt](3)
-:: Print u32 value as decimal into given byte array
+:: Write a u32 number as decimal into a byte array.
 
 : [u32_fmtg](3)
-:: Print u32 value as decimal, using coma as thousand separator, into given byte
-:: array
+:: Write a u32 number as decimal, using coma as thousand separator, into a
+:: byte array.
 
 : [u32_bfmt](3)
-:: Same as [u32_fmt](3) but as binary
+:: Similar to [u32_fmt](3) but as binary.
 
 : [u32_ofmt](3)
-:: Same as [u32_fmt](3) but as octal
+:: Similar to [u32_fmt](3) but as octal.
 
 : [u32_xfmt](3)
-:: Same as [u32_fmt](3) but as hexadecimal
+:: Similar to [u32_fmt](3) but as hexadecimal.
 
-: [u320_fmt](3)
-:: Same as [u32_fmt](3) but filling with zeroes if less than given size
+: [u32_0fmt](3)
+:: Similar to [u32_fmt](3) but filling with zeroes if less than given size.
 
-: [u320_fmtg](3)
-:: Same as [u32_fmtg](3) but filling with zeroes if less than given size
+: [u32_0fmtg](3)
+:: Similar to [u32_fmtg](3) but filling with zeroes if less than given size.
 
-: [u320_bfmt](3)
-:: Same as [u32_bfmt](3) but filling with zeroes if less than given size
+: [u32_0bfmt](3)
+:: Similar to [u32_bfmt](3) but filling with zeroes if less than given size.
 
-: [u320_ofmt](3)
-:: Same as [u32_ofmt](3) but filling with zeroes if less than given size
+: [u32_0ofmt](3)
+:: Similar to [u32_ofmt](3) but filling with zeroes if less than given size.
 
-: [u320_xfmt](3)
-:: Same as [u32_xfmt](3) but filling with zeroes if less than given size
+: [u32_0xfmt](3)
+:: Similar to [u32_xfmt](3) but filling with zeroes if less than given size.
 
 : [u32_scan](3)
-:: Read given byte array for decimal u32 value and load into given variable
+:: Read a u32 value from a byte array.
 
 : [u32_bscan](3)
-:: Same as [u32_scan](3) but for binary value
+:: Similar to [u32_scan](3) but for binary value.
 
 : [u32_oscan](3)
-:: Same as [u32_scan](3) but for octal value
+:: Similar to [u32_scan](3) but for octal value.
 
 : [u32_xscan](3)
-:: Same as [u32_scan](3) but for hexadecimal value
+:: Similar to [u32_scan](3) but for hexadecimal value.
 
-: [u320_scan](3)
-:: Same as [u32_scan](3) but expects a NUL-terminated string
+: [u32_scan0](3)
+:: Similar to [u32_scan](3) but expects a NUL-terminated string.
 
-: [u320_bscan](3)
-:: Same as [u32_bscan](3) but expects a NUL-terminated string
+: [u32_bscan0](3)
+:: Similar to [u32_bscan](3) but expects a NUL-terminated string.
 
-: [u320_oscan](3)
-:: Same as [u32_oscan](3) but expects a NUL-terminated string
-
-: [u320_xscan](3)
-:: Same as [u32_xscan](3) but expects a NUL-terminated string
+: [u32_oscan0](3)
+:: Similar to [u32_oscan](3) but expects a NUL-terminated string.
 
+: [u32_xscan0](3)
+:: Similar to [u32_xscan](3) but expects a NUL-terminated string.
diff --git a/src/doc/u32.h/u320_bfmt.3.md b/src/doc/u32.h/u32_0bfmt.3.md
similarity index 100%
rename from src/doc/u32.h/u320_bfmt.3.md
rename to src/doc/u32.h/u32_0bfmt.3.md
diff --git a/src/doc/u32.h/u320_fmt.3.md b/src/doc/u32.h/u32_0fmt.3.md
similarity index 100%
rename from src/doc/u32.h/u320_fmt.3.md
rename to src/doc/u32.h/u32_0fmt.3.md
diff --git a/src/doc/u32.h/u320_ofmt.3.md b/src/doc/u32.h/u32_0fmtg.3.md
similarity index 100%
rename from src/doc/u32.h/u320_ofmt.3.md
rename to src/doc/u32.h/u32_0fmtg.3.md
diff --git a/src/doc/u32.h/u320_xfmt.3.md b/src/doc/u32.h/u32_0ofmt.3.md
similarity index 100%
rename from src/doc/u32.h/u320_xfmt.3.md
rename to src/doc/u32.h/u32_0ofmt.3.md
diff --git a/src/doc/u32.h/u32_0xfmt.3.md b/src/doc/u32.h/u32_0xfmt.3.md
new file mode 120000
index 0000000..13a02af
--- /dev/null
+++ b/src/doc/u32.h/u32_0xfmt.3.md
@@ -0,0 +1 @@
+u32_fmt.3.md
\ No newline at end of file
diff --git a/src/doc/u32.h/u320_bscan.3.md b/src/doc/u32.h/u32_bscan0.3.md
similarity index 100%
rename from src/doc/u32.h/u320_bscan.3.md
rename to src/doc/u32.h/u32_bscan0.3.md
diff --git a/src/doc/u32.h/u32_fmt.3.md b/src/doc/u32.h/u32_fmt.3.md
index 1cab022..02595ce 100644
--- a/src/doc/u32.h/u32_fmt.3.md
+++ b/src/doc/u32.h/u32_fmt.3.md
@@ -3,13 +3,13 @@
 
 # NAME
 
-u32\_fmt, u32\_fmtg, u320\_fmt - print an u32 as decimal value into a byte array
+u32_fmt, u32_fmtg, u32_0fmt - write an u32 as decimal value into a byte array
 
-u32\_xfmt, u320\_xfmt - print an u32 as hexadecimal value into a byte array
+u32_xfmt, u32_0xfmt - write an u32 as hexadecimal value into a byte array
 
-u32\_ofmt, u320\_ofmt - print an u32 as octal value into a byte array
+u32_ofmt, u32_0ofmt - write an u32 as octal value into a byte array
 
-u32\_bfmt, u320\_bfmt - print an u32 as binary value into a byte array
+u32_bfmt, u32_0bfmt - write an u32 as binary value into a byte array
 
 
 # SYNOPSIS
@@ -18,43 +18,44 @@ u32\_bfmt, u320\_bfmt - print an u32 as binary value into a byte array
 
 ```pre hl
 size_t u32_fmt(char *<em>s</em>, u32 <em>u</em>)
-size_t u320_fmt(char *<em>s</em>, u32 <em>u</em>, size_t <em>min</em>)
+size_t u32_0fmt(char *<em>s</em>, u32 <em>u</em>, size_t <em>min</em>)
 
 size_t u32_fmtg(char *<em>s</em>, u32 <em>u</em>)
-size_t u320_fmtg(char *<em>s</em>, u32 <em>u</em>, size_t <em>min</em>)
+size_t u32_0fmtg(char *<em>s</em>, u32 <em>u</em>, size_t <em>min</em>)
 
 size_t u32_xfmt(char *<em>s</em>, u32 <em>u</em>)
-size_t u320_xfmt(char *<em>s</em>, u32 <em>u</em>, size_t <em>min</em>)
+size_t u32_0xfmt(char *<em>s</em>, u32 <em>u</em>, size_t <em>min</em>)
 
 size_t u32_ofmt(char *<em>s</em>, u32 <em>u</em>)
-size_t u320_ofmt(char *<em>s</em>, u32 <em>u</em>, size_t <em>min</em>)
+size_t u32_0ofmt(char *<em>s</em>, u32 <em>u</em>, size_t <em>min</em>)
 
 size_t u32_bfmt(char *<em>s</em>, u32 <em>u</em>)
-size_t u320_bfmt(char *<em>s</em>, u32 <em>u</em>, size_t <em>min</em>)
+size_t u32_0bfmt(char *<em>s</em>, u32 <em>u</em>, size_t <em>min</em>)
 ```
 
 # DESCRIPTION
 
-The `u32_fmt`() function will put into `s` the value of `u` in decimal.
-The `u320_fmt`() function will put into `s` the value of `u` in decimal,
+The `u32_fmt`() macro will write into `s` the value of `u` in decimal.
+The `u32_0fmt`() macro will write into `s` the value of `u` in decimal,
 prefixing it with leading zeroes if it requires less than `min` characters to do
 so.
 
-The `u32_fmtg`() and `u320_fmtg`() function are similar, only they will use a
+The `u32_fmtg`() and `u32_0fmtg`() macros are similar, only they will use a
 coma (`,`) as thousand separator as needed.
 
-The `u32_xfmt`() and `u320_xfmt`() functions are similar, only putting the value
+The `u32_xfmt`() and `u32_0xfmt`() macros are similar, only putting the value
 of `u` in hexadecimal.
 
-The `u32_ofmt`() and `u320_ofmt`() functions are similar, only putting the value
+The `u32_ofmt`() and `u32_0ofmt`() macros are similar, only putting the value
 of `u` in octal.
 
-The `u32_bfmt`() and `u320_bfmt`() functions are similar, only putting the value
+The `u32_bfmt`() and `u32_0bfmt`() macros are similar, only putting the value
 of `u` in binary.
 
 It is possible to use `NULL` as `s` to only have length computation performed.
 
-Note that those are macros to [u64_fmt_generic](3).
+! INFO: Generic functions
+! Note that those are macros to [u64_fmt_generic](3) and [u64_0fmt_generic](3).
 
 ## Constants
 
diff --git a/src/doc/u32.h/u32_le.3.md b/src/doc/u32.h/u32_le.3.md
index d2e6aea..6c6ec25 100644
--- a/src/doc/u32.h/u32_le.3.md
+++ b/src/doc/u32.h/u32_le.3.md
@@ -3,11 +3,9 @@
 
 # NAME
 
-u32\_le, u32\_be - convert a value to little\/big endian
+u32_le, u32_be, u32p_le, u32p_be - convert an u32 to little/big endian
 
-u32p\_le, u32p\_be - convert an u32 into little\/big endian
-
-u32pa\_le, u32pa\_be - convert an array of u32 into little\/big endian
+u32pa_le, u32pa_be - convert an array of u32 into little/big endian
 
 # SYNOPSIS
 
@@ -20,25 +18,26 @@ u32 u32_be(u32 <em>u</em>)
 void u32p_le(u32 *<em>val</em>)
 void u32p_be(u32 *<em>val</em>)
 
-void u32pa_le(u32 *<em>val</em>, size_t <em>length</em>)
-void u32pa_be(u32 *<em>val</em>, size_t <em>length</em>)
+void u32pa_le(u32 *<em>val</em>, size_t <em>len</em>)
+void u32pa_be(u32 *<em>val</em>, size_t <em>len</em>)
 ```
 
 # DESCRIPTION
 
 All of these aim to ensure a value or variable is in expected endianness.
 
-The `u32_le`() and `u32_be`() functions will return the value after having read
-the given number `u` as a little endian and big endian value respectively.
+The `u32_le`() and `u32_be`() macros will return the value after having read
+the given number `u` as a little endian or big endian value, respectively.
 
-The `u32p_le`() and `u32p_be`() functions are similar, only they take a pointer
-to an u32 and will convert it into little endian and big endian, respectively.
+The `u32p_le`() and `u32p_be`() macros are similar, only they take a pointer
+to an u32 and will convert it into little endian or big endian, respectively.
 
-Finally the `u32pa_le`() and `u32pa_be`() are similar to the previous two, only
-they take an array of u32 of size `length` and convert every element.
+Finally the `u32pa_le`() and `u32pa_be`() macros are similar to the previous
+two, only they take an array of u32 of size `len` and convert every element.
 
-These are actually macros to the relevant `uint32_*` functions as needed, i.e.
-if the requested endianness is that of the host, no operation is performed.
+! NOTE:
+! Note that these are macros they may be either no-op or byte swapping functions
+! depending on the endianness of the host.
 
 # RETURN VALUE
 
diff --git a/src/doc/u32.h/u320_oscan.3.md b/src/doc/u32.h/u32_oscan0.3.md
similarity index 100%
rename from src/doc/u32.h/u320_oscan.3.md
rename to src/doc/u32.h/u32_oscan0.3.md
diff --git a/src/doc/u32.h/u32_pack.3.md b/src/doc/u32.h/u32_pack.3.md
index 8c6645f..06fe4b4 100644
--- a/src/doc/u32.h/u32_pack.3.md
+++ b/src/doc/u32.h/u32_pack.3.md
@@ -3,8 +3,8 @@
 
 # NAME
 
-u32\_pack, u32\_unpack, u32\_pack\_big, u32\_unpack\_big - pack\/unpack an
-integer (u32) into\/from a byte array
+u32_pack, u32_unpack, u32_pack_big, u32_unpack_big - store/read an u32 into/from
+a byte array
 
 # SYNOPSIS
 
@@ -13,21 +13,23 @@ integer (u32) into\/from a byte array
 ```pre hl
 void u32_pack(void *<em>dst</em>, u32 <em>val</em>)
 void u32_unpack(u32 *<em>val</em>, const void *<em>sce</em>)
+
 void u32_pack_big(void *<em>dst</em>, u32 <em>val</em>)
 void u32_unpack_big(u32 *<em>val</em>, const void *<em>sce</em>)
 ```
 
 # DESCRIPTION
 
-All of these aim to either pack the given integer (u32) `val` into the specified
-byte array `dst`, or unpack from the specified byte array `sce` the integer
-value into the pointed `val`.
+All of these aim to either store the given number `val` into the specified
+byte array `dst`, or read a number from the specified byte array `sce` and set
+the value pointed by `val` to its value.
+
+The `u32_pack`() function stores the number `val` into the 4 bytes pointed by
+`dst`, encoded as little endian.
 
-The `u32_pack`() function packs `val` into 4 bytes encoded as little endian, the
-`u32_pack_big`() function does the same encoded as big endian.
+The `u32_unpack`() function reads 4 bytes pointed by `sce` as little endian
+encoded number, setting the value pointed by `val` to its value.
 
-The `u32_unpack` family does the same, only unpacking from the byte array `sce`
-into `val`
+The `u32_pack_big`() function is similar to `u32_pack`() only as big endian.
 
-These are actually macros to the relevant `uint32_*` functions, offering a
-slightly different interface.
+The `u32_unpack_big`() function is similar to `u32_unpack`() only as big endian.
diff --git a/src/doc/u32.h/u32_scan.3.md b/src/doc/u32.h/u32_scan.3.md
index 4e07202..c6e9ef1 100644
--- a/src/doc/u32.h/u32_scan.3.md
+++ b/src/doc/u32.h/u32_scan.3.md
@@ -3,13 +3,13 @@
 
 # NAME
 
-u32\_scan, u320\_scan - Read an u32 value from a decimal string
+u32_scan, u32_scan0 - Read an u32 value from a decimal string
 
-u32\_xscan, u320\_xscan - Read an u32 value from an hexadecimal string
+u32_xscan, u32_xscan0 - Read an u32 value from an hexadecimal string
 
-u32\_oscan, u320\_oscan - Read an u32 value from an octal string
+u32_oscan, u32_oscan0 - Read an u32 value from an octal string
 
-u32\_bscan, u320\_bscan - Read an u32 value from a binary string
+u32_bscan, u32_bscan0 - Read an u32 value from a binary string
 
 
 # SYNOPSIS
@@ -18,16 +18,16 @@ u32\_bscan, u320\_bscan - Read an u32 value from a binary string
 
 ```pre hl
 size_t u32_scan(u32 *<em>dst</em>, const char *<em>s</em>)
-size_t u320_scan(u32 *<em>dst</em>, const char *<em>s</em>)
+size_t u32_scan0(u32 *<em>dst</em>, const char *<em>s</em>)
 
 size_t u32_xscan(u32 *<em>dst</em>, const char *<em>s</em>)
-size_t u320_xscan(u32 *<em>dst</em>, const char *<em>s</em>)
+size_t u32_xscan0(u32 *<em>dst</em>, const char *<em>s</em>)
 
 size_t u32_oscan(u32 *<em>dst</em>, const char *<em>s</em>)
-size_t u320_oscan(u32 *<em>dst</em>, const char *<em>s</em>)
+size_t u32_oscan0(u32 *<em>dst</em>, const char *<em>s</em>)
 
 size_t u32_bscan(u32 *<em>dst</em>, const char *<em>s</em>)
-size_t u320_bscan(u32 *<em>dst</em>, const char *<em>s</em>)
+size_t u32_bscan0(u32 *<em>dst</em>, const char *<em>s</em>)
 ```
 
 # DESCRIPTION
@@ -35,30 +35,30 @@ size_t u320_bscan(u32 *<em>dst</em>, const char *<em>s</em>)
 The `u32_scan`() function will place into `dst` the number read as a decimal
 value from the string `s`, stopping as soon as a character isn't valid.
 
-The `u320_scan`() function is similar but expects the string to contain a valid
+The `u32_scan0`() function is similar but expects the string to contain a valid
 value and nothing else, stopping with a NUL-terminating byte.
 
-The `u32_xscan`() and `u320_xscan`() functions are similar, but expecting an
+The `u32_xscan`() and `u32_xscan0`() functions are similar, but expecting an
 hexadecimal value in `s`.
 
-The `u32_oscan`() and `u320_oscan`() functions are similar, but expecting an
+The `u32_oscan`() and `u32_oscan0`() functions are similar, but expecting an
 octal value in `s`.
 
-The `u32_bscan`() and `u320_bscan`() functions are similar, but expecting a
+The `u32_bscan`() and `u32_bscan0`() functions are similar, but expecting a
 binary value in `s`.
 
 
 # RETURN VALUE
 
-The `u32_*` family of functions return the number of characters read from `s`
-(starting at 0 when the first character is invalid).
+The `u32_*scan` family of functions return the number of characters read from
+`s` (starting at 0 when the first character is invalid).
 
-The `u320_*` family of functions return the number of characters read from `s`
-or 0 on error.
+The `u32_*scan0` family of functions return the number of characters read from
+`s` or 0 on error.
 
 # ERRORS
 
-The `u320_*` family of functions may fail and set `errno` if :
+The `u32_*scan0` family of functions may fail and set `errno` if :
 
 : *EINVAL*
 :: Invalid character in `s`
diff --git a/src/doc/u32.h/u320_scan.3.md b/src/doc/u32.h/u32_scan0.3.md
similarity index 100%
rename from src/doc/u32.h/u320_scan.3.md
rename to src/doc/u32.h/u32_scan0.3.md
diff --git a/src/doc/u32.h/u320_xscan.3.md b/src/doc/u32.h/u32_xscan0.3.md
similarity index 100%
rename from src/doc/u32.h/u320_xscan.3.md
rename to src/doc/u32.h/u32_xscan0.3.md
diff --git a/src/liblimb/include/limb/u32.h b/src/liblimb/include/limb/u32.h
index 883fb2c..f89a95d 100644
--- a/src/liblimb/include/limb/u32.h
+++ b/src/liblimb/include/limb/u32.h
@@ -33,20 +33,20 @@
 #define u32_ofmt(s,u)               u64_fmt_generic(s, (u),  8, 0, 0)
 #define u32_bfmt(s,u)               u64_fmt_generic(s, (u),  2, 0, 0)
 
-#define u320_fmt(s,u,m)             u640_fmt_generic(s, (u), 10, (m), '0', 0, 0)
-#define u320_fmtg(s,u,m)            u640_fmt_generic(s, (u), 10, (m), '0', 3, ',')
-#define u320_xfmt(s,u,m)            u640_fmt_generic(s, (u), 16, (m), '0', 0, 0)
-#define u320_ofmt(s,u,m)            u640_fmt_generic(s, (u),  8, (m), '0', 0, 0)
-#define u320_bfmt(s,u,m)            u640_fmt_generic(s, (u),  2, (m), '0', 0, 0)
+#define u32_0fmt(s,u,m)             u64_0fmt_generic(s, (u), 10, (m), '0', 0, 0)
+#define u32_0fmtg(s,u,m)            u64_0fmt_generic(s, (u), 10, (m), '0', 3, ',')
+#define u32_0xfmt(s,u,m)            u64_0fmt_generic(s, (u), 16, (m), '0', 0, 0)
+#define u32_0ofmt(s,u,m)            u64_0fmt_generic(s, (u),  8, (m), '0', 0, 0)
+#define u32_0bfmt(s,u,m)            u64_0fmt_generic(s, (u),  2, (m), '0', 0, 0)
 
 #define u32_scan(dst,s)             uint32_scan(s, (dst))
 #define u32_xscan(dst,s)            uint32_xscan(s, (dst))
 #define u32_oscan(dst,s)            uint32_oscan(s, (dst))
 #define u32_bscan(dst,s)            uint32_bscan(s, (dst))
 
-#define u320_scan(dst,s)            uint320_scan(s, (dst))
-#define u320_xscan(dst,s)           uint320_xscan(s, (dst))
-#define u320_oscan(dst,s)           uint320_oscan(s, (dst))
-#define u320_bscan(dst,s)           uint320_bscan(s, (dst))
+#define u32_scan0(dst,s)            uint320_scan(s, (dst))
+#define u32_xscan0(dst,s)           uint320_xscan(s, (dst))
+#define u32_oscan0(dst,s)           uint320_oscan(s, (dst))
+#define u32_bscan0(dst,s)           uint320_bscan(s, (dst))
 
 #endif /* LIMB_U32_H */