author | Olivier Brunel
<jjk@jjacky.com> 2023-07-02 16:36:13 UTC |
committer | Olivier Brunel
<jjk@jjacky.com> 2023-07-24 10:16:42 UTC |
parent | c7516477ba00df18aeea16f46d7092d6d042ca02 |
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 */