Develop the msg chunklet further

- Add reverse-put functions for stack-based and/or left-pad-inspired
  use cases.
- Fix an incorrect return value.
- Clean up the doc comments, fixing a few errors and omissions.
- Make some trivial functions static inline.

1 files changed, 488 insertions, 84 deletions

diff --git a/src/chunklets/msg.h b/src/chunklets/msg.h
index c40bdbe..17a097d 100644
--- a/src/chunklets/msg.h
+++ b/src/chunklets/msg.h
@@ -1,5 +1,5 @@
 /*
- * Copyright © 2023 Michael Smith <mikesmiffy128@gmail.com>
+ * Copyright © 2025 Michael Smith <mikesmiffy128@gmail.com>
  *
  * Permission to use, copy, modify, and/or distribute this software for any
  * purpose with or without fee is hereby granted, provided that the above
@@ -25,36 +25,86 @@ extern "C" {
 #endif
 
 /*
- * Writes a nil (null) message to the buffer out. Always writes a single byte.
+ * Writes a nil (null) message to the buffer `out`.
+ *
+ * `out` must point to at least 1 byte of space.
+ *
+ * Always writes a single byte.
+ */
+static inline void msg_putnil(unsigned char *out) {
+	*out = 0xC0;
+}
+
+/*
+ * Writes a nil (null) message immediately before the pointer `end`.
+ *
+ * `end` must point immediately beyond at least 1 byte of space.
+ *
+ * Always writes a single byte.
  *
- * out must point to at least 1 byte.
  */
-void msg_putnil(unsigned char *out);
+static inline void msg_rputnil(unsigned char *end) {
+	end[-1] = 0xC0;
+}
+
+/*
+ * Writes the boolean `val` to the buffer `out`.
+ *
+ * `out` must point to at least 1 byte of space.
+ *
+ * Always writes a single byte.
+ */
+static inline void msg_putbool(unsigned char *out, _msg_Bool val) {
+	*out = 0xC2 | val;
+}
 
 /*
- * Writes the boolean val to the buffer out. Always writes a single byte.
+ * Writes the boolean `val` immediately before the pointer `end`.
+ *
+ * `end` must point immediately beyond at least 1 byte of space.
  *
- * out must point to at least 1 byte.
+ * Always writes a single byte.
  */
-void msg_putbool(unsigned char *out, _msg_Bool val);
+static inline void msg_rputbool(unsigned char *end, _msg_Bool val) {
+	end[-1] = 0xC2 | val;
+}
 
 /*
- * Writes the integer val in the range [-32, 127] to the buffer out. Values
- * outside this range will produce an undefined encoding. Always writes a single
- * byte.
+ * Writes the integer `val` in the range [-32, 127] to the buffer `out`. Values
+ * outside this range will produce an undefined encoding.
+ *
+ * `out` must point to at least 1 byte of space.
  *
- * out must point to at least 1 byte.
+ * Always writes a single byte.
  *
  * It is recommended to use msg_puts() for arbitrary signed values or msg_putu()
  * for arbitrary unsigned values. Those functions will produce the smallest
  * possible encoding for any value.
  */
-void msg_puti7(unsigned char *out, signed char val);
+static inline void msg_puti7(unsigned char *out, signed char val) {
+	*out = val; // a fixnum is just the literal byte! genius!
+}
+
+/*
+ * Writes the integer `val` in the range [-32, 127] immediately before the
+ * pointer `end`. Values outside this range will produce an undefined encoding.
+ *
+ * `end` must point immediately beyond at least 1 byte of space.
+ *
+ * Always writes a single byte.
+ *
+ * It is recommended to use msg_rputs() for arbitrary signed values or
+ * msg_rputu() for arbitrary unsigned values. Those functions will produce the
+ * smallest possible encoding for any value.
+ */
+static inline void msg_rputi7(unsigned char *end, signed char val) {
+	end[-1] = val;
+}
 
 /*
- * Writes the signed int val in the range [-128, 127] to the buffer out.
+ * Writes the signed int `val` in the range [-128, 127] to the buffer `out`.
  *
- * out must point to at least 2 bytes.
+ * `out` must point to at least 2 bytes of space.
  *
  * Returns the number of bytes written, one of {1, 2}.
  *
@@ -64,9 +114,22 @@ void msg_puti7(unsigned char *out, signed char val);
 int msg_puts8(unsigned char *out, signed char val);
 
 /*
- * Writes the unsigned int val in the range [0, 255] to the buffer out.
+ * Writes the signed int `val` in the range [-128, 127] immediately before the
+ * pointer `end`.
+ *
+ * `end` must point immediately beyond at least 2 bytes of space.
+ *
+ * Returns the number of bytes written, one of {1, 2}.
+ *
+ * It is recommended to use msg_rputs() for arbitrary signed values. That
+ * function will produce the smallest possible encoding for any value.
+ */
+int msg_rputs8(unsigned char *end, signed char val);
+
+/*
+ * Writes the unsigned int `val` in the range [0, 255] to the buffer `out`.
  *
- * out must point to at least 2 bytes.
+ * `out` must point to at least 2 bytes of space.
  *
  * Returns the number of bytes written, one of {1, 2}.
  *
@@ -76,9 +139,22 @@ int msg_puts8(unsigned char *out, signed char val);
 int msg_putu8(unsigned char *out, unsigned char val);
 
 /*
- * Writes the signed int val in the range [-65536, 65535] to the buffer out.
+ * Writes the unsigned int `val` in the range [0, 255] immediately before the
+ * pointer `end`.
+ *
+ * `end` must point immediately beyond at least 2 bytes of space.
+ *
+ * Returns the number of bytes written, one of {1, 2}.
+ *
+ * It is recommended to use msg_rputu() for arbitrary unsigned values. That
+ * function will produce the smallest possible encoding for any value.
+ */
+int msg_rputu8(unsigned char *end, unsigned char val);
+
+/*
+ * Writes the signed int `val` in the range [-32768, 32767] to the buffer `out`.
  *
- * out must point to at least 3 bytes.
+ * `out` must point to at least 3 bytes of space.
  *
  * Returns the number of bytes written, one of {1, 2, 3}.
  *
@@ -88,9 +164,22 @@ int msg_putu8(unsigned char *out, unsigned char val);
 int msg_puts16(unsigned char *out, short val);
 
 /*
- * Writes the unsigned int val in the range [0, 65536] to the buffer out.
+ * Writes the signed int `val` in the range [-32768, 32767] immediately before
+ * the pointer `end`.
+ *
+ * `end` must point immediately beyond at least 3 bytes of space.
+ *
+ * Returns the number of bytes written, one of {1, 2, 3}.
+ *
+ * It is recommended to use msg_rputs() for arbitrary signed values. That
+ * function will produce the smallest possible encoding for any value.
+ */
+int mmsg_rputs16(unsigned char *end, short val);
+
+/*
+ * Writes the unsigned int `val` in the range [0, 65536] to the buffer `out`.
  *
- * out must point to at least 3 bytes.
+ * `out` must point to at least 3 bytes of space.
  *
  * Returns the number of bytes written, one of {1, 2, 3}.
  *
@@ -100,10 +189,23 @@ int msg_puts16(unsigned char *out, short val);
 int msg_putu16(unsigned char *out, unsigned short val);
 
 /*
- * Writes the signed int val in the range [-2147483648, 2147483647] to the
- * buffer out.
+ * Writes the signed int `val` in the range [0, 65536] immediately before the
+ * pointer `end`.
+ *
+ * `end` must point immediately beyond at least 3 bytes of space.
+ *
+ * Returns the number of bytes written, one of {1, 2}.
+ *
+ * It is recommended to use msg_rputu() for arbitrary unsigned values. That
+ * function will produce the smallest possible encoding for any value.
+ */
+int msg_rputu16(unsigned char *end, unsigned short val);
+
+/*
+ * Writes the signed int `val` in the range [-2147483648, 2147483647] to the
+ * buffer `out`.
  *
- * out must point to at least 5 bytes.
+ * `out` must point to at least 5 bytes of space.
  *
  * Returns the number of bytes written, one of {1, 2, 3, 5}.
  *
@@ -113,9 +215,23 @@ int msg_putu16(unsigned char *out, unsigned short val);
 int msg_puts32(unsigned char *out, int val);
 
 /*
- * Writes the unsigned int val in the range [0, 4294967295] to the buffer out.
+ * Writes the signed int `val` in the range [-2147483648, 2147483647]
+ * immediately before the pointer `end`.
  *
- * out must point to at least 5 bytes.
+ * `end` must point immediately beyond at least least 5 bytes of space.
+ *
+ * Returns the number of bytes written, one of {1, 2, 3, 5}.
+ *
+ * It is recommended to use msg_rputs() for arbitrary signed values. That
+ * function will produce the smallest possible encoding for any value.
+ */
+int msg_rputs32(unsigned char *end, int val);
+
+/*
+ * Writes the unsigned int `val` in the range [0, 4294967295] to the buffer
+ * `out`.
+ *
+ * `out` must point to at least 5 bytes of space.
  *
  * Returns the number of bytes written, one of {1, 2, 3, 5}.
  *
@@ -125,64 +241,145 @@ int msg_puts32(unsigned char *out, int val);
 int msg_putu32(unsigned char *out, unsigned int val);
 
 /*
- * Writes the signed int val in the range [-9223372036854775808,
- * 9223372036854775807] to the buffer out.
+ * Writes the unsigned int `val` in the range [0, 4294967295] immediately before
+ * the pointer `end`.
+ *
+ * `end` must point immediately beyond at least 5 bytes of space.
+ *
+ * Returns the number of bytes written, one of {1, 2, 3, 5}.
+ *
+ * It is recommended to use msg_rputu() for arbitrary unsigned values. That
+ * function will produce the smallest possible encoding for any value.
+ */
+int msg_rputu32(unsigned char *end, unsigned int val);
+
+/*
+ * Writes the signed int `val` in the range [-9223372036854775808,
+ * 9223372036854775807] to the buffer `out`.
  *
- * out must point to at least 9 bytes.
+ * `out` must point to at least 9 bytes of space.
  *
  * Returns the number of bytes written, one of {1, 2, 3, 5, 9}.
  */
 int msg_puts(unsigned char *out, long long val);
 
 /*
- * Writes the unsigned int val in the range [0, 18446744073709551616] to the
- * buffer out.
+ * Writes the signed int `val` in the range [-9223372036854775808,
+ * 9223372036854775807] immediately before the pointer `end`.
+ *
+ * `end` must point immediately beyond at least 9 bytes of space.
+ *
+ * Returns the number of bytes written, one of {1, 2, 3, 5, 9}.
+ */
+int msg_rputs(unsigned char *end, long long val);
+
+/*
+ * Writes the unsigned int `val` in the range [0, 18446744073709551616] to the
+ * buffer `out`.
  *
- * out must point to at least 9 bytes.
+ * `out` must point to at least 9 bytes of space.
  *
  * Returns the number of bytes written, one of {1, 2, 3, 5, 9}.
  */
 int msg_putu(unsigned char *out, unsigned long long val);
 
 /*
- * Writes the IEEE 754 single-precision float val to the buffer out. Always
- * writes 5 bytes.
+ * Writes the unsigned int `val` in the range [0, 18446744073709551616]
+ * immediately before the pointer `end`.
  *
- * out must point to at least 5 bytes.
+ * `end` must point immediately beyond at least 9 bytes of space.
+ *
+ * Returns the number of bytes written, one of {1, 2, 3, 5, 9}.
+ */
+int msg_rputu(unsigned char *end, unsigned long long val);
+
+/*
+ * Writes the IEEE 754 single-precision float `val` to the buffer `out`.
+ *
+ * `out` must point to at least 5 bytes of space.
+ *
+ * Always writes 5 bytes.
  */
 void msg_putf(unsigned char *out, float val);
 
 /*
- * Writes the IEEE 754 double-precision float val to the buffer out.
+ * Writes the IEEE 754 single-precision float `val` immediately before the pointer
+ * `end`.
+ *
+ * `end` must point immediately beyond at least 5 bytes of space.
+ *
+ * Always writes 5 bytes.
+ */
+static inline void msg_rputf(unsigned char *end, float val) {
+	msg_putf(end - 5, val);
+}
+
+/*
+ * Writes the IEEE 754 double-precision float `val` to the buffer `out`, or writes
+ * a single-precision float if the exact value is the same.
  *
- * out must point to at least 9 bytes.
+ * `out` must point to at least 9 bytes of space.
  *
  * Returns the number of bytes written, one of {5, 9}.
  */
 int msg_putd(unsigned char *out, double val);
 
 /*
- * Writes the string size sz in the range [0, 31] to the buffer out. Values
- * outside this range will produce an undefined encoding. Always writes a single
- * byte.
+ * Writes the IEEE 754 double-precision float `val` immediately before the pointer
+ * `end`, or writes a single-precision float if the exact value is the same.
+ *
+ * `end` must point immediately beyond at least 9 bytes of space.
+ *
+ * Returns the number of bytes written, one of {5, 9}.
+ */
+int msg_rputd(unsigned char *end, double val);
+
+/*
+ * Writes the string size `sz` in the range [0, 31] to the buffer `out`. Values
+ * outside this range will produce an undefined encoding.
+ *
+ * `out` must point to at least 1 byte of space.
+ *
+ * Always writes a single byte.
  *
  * In a complete message stream, a size of N must be immediately followed by N
  * bytes of the actual string, which must be valid UTF-8.
  *
- * out must point to at least 1 byte.
- *
  * It is recommended to use msg_putssz() for arbitrary string sizes. That
  * function will produce the smallest possible encoding for any size value.
  */
-void msg_putssz5(unsigned char *out, int sz);
+static inline void msg_putssz5(unsigned char *out, int sz) {
+	*out = 0xA0 | sz;
+}
 
 /*
- * Writes the string size sz in the range [0, 255] to the buffer out.
+ * Writes the string size `sz` in the range [0, 31] immediately before the pointer
+ * `end`. Values outside this range will produce an undefined encoding.
+ *
+ * `end` must point immediately beyond at least 1 byte of space.
+ *
+ * Always writes a single byte.
  *
  * In a complete message stream, a size of N must be immediately followed by N
  * bytes of the actual string, which must be valid UTF-8.
  *
- * out must point to at least 2 bytes.
+ * It is recommended to use msg_rputssz() for arbitrary string sizes. That
+ * function will produce the smallest possible encoding for any size value.
+ */
+static inline void msg_rputssz5(unsigned char *end, int sz) {
+	msg_putssz5(end - 1, sz);
+}
+
+/*
+ * Writes the string size `sz` in the range [0, 255] to the buffer `out`. Values
+ * outside this range will produce an undefined encoding.
+ *
+ * `out` must point to at least 2 bytes of space.
+ *
+ * Returns the number of bytes written, one of {1, 2}.
+ *
+ * In a complete message stream, a size of N must be immediately followed by N
+ * bytes of the actual string, which must be valid UTF-8.
  *
  * It is recommended to use msg_putssz() for arbitrary string sizes. That
  * function will produce the smallest possible encoding for any size value.
@@ -190,12 +387,31 @@ void msg_putssz5(unsigned char *out, int sz);
 int msg_putssz8(unsigned char *out, int sz);
 
 /*
- * Writes the string size sz in the range [0, 65535] to the buffer out.
+ * Writes the string size `sz` in the range [0, 255] immediately before the
+ * pointer `end`. Values outside this range will produce an undefined encoding.
+ *
+ * `end` must point immediately beyond at least 2 byte of space.
+ *
+ * Returns the number of bytes written, one of {1, 2}.
  *
  * In a complete message stream, a size of N must be immediately followed by N
  * bytes of the actual string, which must be valid UTF-8.
  *
- * out must point to at least 3 bytes.
+ * It is recommended to use msg_rputssz() for arbitrary string sizes. That
+ * function will produce the smallest possible encoding for any size value.
+ */
+int msg_rputssz8(unsigned char *end, int sz);
+
+/*
+ * Writes the string size `sz` in the range [0, 65535] to the buffer `out`. Values
+ * outside this range will produce an undefined encoding.
+ *
+ * `out` must point to at least 3 bytes of space.
+ *
+ * Returns the number of bytes written, one of {1, 2, 3}.
+ *
+ * In a complete message stream, a size of N must be immediately followed by N
+ * bytes of the actual string, which must be valid UTF-8.
  *
  * It is recommended to use msg_putssz() for arbitrary string sizes. That
  * function will produce the smallest possible encoding for any size value.
@@ -203,38 +419,92 @@ int msg_putssz8(unsigned char *out, int sz);
 int msg_putssz16(unsigned char *out, int sz);
 
 /*
- * Writes the string size sz in the range [0, 4294967295] to the buffer out.
+ * Writes the string size `sz` in the range [0, 65535] immediately before the
+ * pointer `end`. Values outside this range will produce an undefined encoding.
+ *
+ * `end` must point immediately beyond at least 3 bytes of space.
+ *
+ * Returns the number of bytes written, one of {1, 2, 3}.
  *
  * In a complete message stream, a size of N must be immediately followed by N
  * bytes of the actual string, which must be valid UTF-8.
  *
- * out must point to at least 5 bytes.
+ * It is recommended to use msg_rputssz() for arbitrary string sizes. That
+ * function will produce the smallest possible encoding for any size value.
+ */
+int msg_rputssz16(unsigned char *end, int sz);
+
+/*
+ * Writes the string size `sz` in the range [0, 4294967295] to the buffer `out`.
+ *
+ * `out` must point to at least 5 bytes of space.
+ *
+ * Returns the number of bytes written, one of {1, 2, 3, 5}.
+ *
+ * In a complete message stream, a size of N must be immediately followed by N
+ * bytes of the actual string, which must be valid UTF-8.
  */
 int msg_putssz(unsigned char *out, unsigned int sz);
 
 /*
- * Writes the binary blob size sz in the range [0, 255] to the buffer out.
+ * Writes the string size `sz` in the range [0, 4294967295] immediately before
+ * the pointer `end`.
+ *
+ * `end` must point immediately beyond at least 5 bytes of space.
+ *
+ * Returns the number of bytes written, one of {1, 2, 3, 5}.
+ *
+ * In a complete message stream, a size of N must be immediately followed by N
+ * bytes of the actual string, which must be valid UTF-8.
+ */
+int msg_rputssz(unsigned char *end, unsigned int sz);
+
+/*
+ * Writes the binary blob size `sz` in the range [0, 255] to the buffer `out`.
+ * Values outside this range will produce an undefined encoding.
+ *
+ * `out` must point to at least 2 bytes of space.
+ *
  * Always writes 2 bytes.
  *
  * In a complete message stream, a size of N must be immediately followed by
  * N bytes of the actual data.
  *
- * out must point to at least 2 bytes.
- *
  * It is recommended to use msg_putbsz() for arbitrary binary blob sizes. That
  * function will produce the smallest possible encoding for any size value.
  */
-void msg_putbsz8(unsigned char *out, int sz);
+static inline void msg_putbsz8(unsigned char *out, int sz) {
+	out[0] = 0xC4; out[1] = sz;
+}
 
 /*
- * Writes the binary blob size sz in the range [0, 65535] to the buffer out.
+ * Writes the binary blob size `sz` in the range [0, 255] immediately before the
+ * pointer `end`. Values outside this range will produce an undefined encoding.
+ *
+ * `end` must point immediately beyond at least 2 bytes of space.
+ *
+ * Always writes 2 bytes.
  *
  * In a complete message stream, a size of N must be immediately followed by
  * N bytes of the actual data.
  *
- * out must point to at least 3 bytes.
+ * It is recommended to use msg_rputbsz() for arbitrary binary blob sizes. That
+ * function will produce the smallest possible encoding for any size value.
+ */
+static inline void msg_rputbsz8(unsigned char *end, int sz) {
+	end[-2] = 0xC4; end[-1] = sz;
+}
+
+/*
+ * Writes the binary blob size `sz` in the range [0, 65535] to the buffer `out`.
+ * Values outside this range will produce an undefined encoding.
  *
- * Returns the number of bytes written, one of {1, 2, 3}.
+ * `out` must point to at least 3 bytes of space.
+ *
+ * Returns the number of bytes written, one of {2, 3}.
+ *
+ * In a complete message stream, a size of N must be immediately followed by
+ * N bytes of the actual data.
  *
  * It is recommended to use msg_putbsz() for arbitrary binary blob sizes. That
  * function will produce the smallest possible encoding for any size value.
@@ -242,104 +512,238 @@ void msg_putbsz8(unsigned char *out, int sz);
 int msg_putbsz16(unsigned char *out, int sz);
 
 /*
- * Writes the binary blob size sz in the range [0, 4294967295] to the buffer out.
+ * Writes the binary blob size `sz` in the range [0, 65535] immediately before
+ * the pointer `end`. Values outside this range will produce an undefined
+ * encoding.
+ *
+ * `end` must point immediately beyond at least 3 bytes of space.
+ *
+ * Returns the number of bytes written, one of {2, 3}.
  *
  * In a complete message stream, a size of N must be immediately followed by
  * N bytes of the actual data.
  *
- * out must point to at least 5 bytes.
+ * It is recommended to use msg_rputbsz() for arbitrary binary blob sizes. That
+ * function will produce the smallest possible encoding for any size value.
+ */
+int msg_rputbsz16(unsigned char *end, int sz);
+
+/*
+ * Writes the binary blob size `sz` in the range [0, 4294967295] to the buffer
+ * `out`.
  *
- * Returns the number of bytes written, one of {1, 2, 3, 5}.
+ * `out` must point to at least 5 bytes of space.
+ *
+ * Returns the number of bytes written, one of {2, 3, 5}.
+ *
+ * In a complete message stream, a size of N must be immediately followed by
+ * N bytes of the actual data.
  */
 int msg_putbsz(unsigned char *out, unsigned int sz);
 
 /*
- * Writes the array size sz in the range [0, 15] to the buffer out. Values
- * outside this range will produce an undefined encoding. Always writes a single
- * byte.
+ * Writes the binary blob size `sz` in the range [0, 4294967295] immediately
+ * before the pointer `end`.
+ *
+ * `end` must point immediately beyond at least 5 bytes of space.
+ *
+ * Returns the number of bytes written, one of {2, 3, 5}.
+ *
+ * In a complete message stream, a size of N must be immediately followed by
+ * N bytes of the actual data.
+ */
+int msg_rputbsz(unsigned char *end, unsigned int sz);
+
+/*
+ * Writes the array size `sz` in the range [0, 15] to the buffer `out`. Values
+ * outside this range will produce an undefined encoding.
+ *
+ * `out` must point to at least 1 byte of space.
+ *
+ * Always writes a single byte.
  *
  * In a complete message stream, a size of N must be immediately followed by N
  * other messages, which form the contents of the array.
  *
- * out must point to at least 1 byte.
- *
  * It is recommended to use msg_putasz() for arbitrary array sizes. That
  * function will produce the smallest possible encoding for any size value.
  */
-void msg_putasz4(unsigned char *out, int sz);
+static inline void msg_putasz4(unsigned char *out, int sz) {
+	*out = 0x90 | sz;
+}
 
 /*
- * Writes the array size sz in the range [0, 65535] to the buffer out.
+ * Writes the array size `sz` in the range [0, 15] immediately before the
+ * pointer `end`. Values outside this range will produce an undefined encoding.
+ *
+ * `end` must point immediately beyond at least 1 byte of space.
+ *
+ * Always writes a single byte.
  *
  * In a complete message stream, a size of N must be immediately followed by N
  * other messages, which form the contents of the array.
  *
- * out must point to at least 3 bytes.
+ * It is recommended to use msg_rputasz() for arbitrary array sizes. That
+ * function will produce the smallest possible encoding for any size value.
+ */
+static inline void msg_rputasz4(unsigned char *end, int sz) {
+	end[-1] = 0x90 | sz;
+}
+
+/*
+ * Writes the array size `sz` in the range [0, 65535] to the buffer `out`.
+ * Values outside this range will produce an undefined encoding.
+ *
+ * `out` must point to at least 3 bytes of space.
  *
  * Returns the number of bytes written, one of {1, 3}.
  *
+ * In a complete message stream, a size of N must be immediately followed by N
+ * other messages, which form the contents of the array.
+ *
  * It is recommended to use msg_putasz() for arbitrary array sizes. That
  * function will produce the smallest possible encoding for any size value.
  */
 int msg_putasz16(unsigned char *out, int sz);
 
 /*
- * Writes the array size sz in the range [0, 4294967295] to the buffer out.
+ * Writes the array size `sz` in the range [0, 65535] immediately before the
+ * pointer `end`.
+ *
+ * `end` must point immediately beyond at least 3 bytes of space.
+ *
+ * Returns the number of bytes written, one of {1, 3}.
  *
  * In a complete message stream, a size of N must be immediately followed by N
  * other messages, which form the contents of the array.
  *
- * out must point to at least 5 bytes.
+ * It is recommended to use msg_rputasz() for arbitrary array sizes. That
+ * function will produce the smallest possible encoding for any size value.
+ */
+int msg_rputasz16(unsigned char *end, int sz);
+
+/*
+ * Writes the array size `sz` in the range [0, 4294967295] to the buffer `out`.
+ *
+ * `out` must point to at least 5 bytes of space.
  *
  * Returns the number of bytes written, one of {1, 3, 5}.
+ *
+ * In a complete message stream, a size of N must be immediately followed by N
+ * other messages, which form the contents of the array.
  */
 int msg_putasz(unsigned char *out, unsigned int sz);
 
 /*
- * Writes the map size sz in the range [0, 15] to the buffer out. Values
- * outside this range will produce an undefined encoding. Always writes a single
- * byte.
+ * Writes the array size `sz` in the range [0, 4294967295] immediately before
+ * the pointer `end`.
  *
- * In a complete message stream, a size of N must be immediately followed by
- * N * 2 other messages, which form the contents of the map as keys followed by
- * values in alternation.
+ * `end` must point immediately beyond at least 5 bytes of space.
+ *
+ * Returns the number of bytes written, one of {1, 3, 5}.
+ *
+ * In a complete message stream, a size of N must be immediately followed by N
+ * other messages, which form the contents of the array.
+ */
+int msg_rputasz(unsigned char *end, unsigned int sz);
+
+/*
+ * Writes the map size `sz` in the range [0, 15] to the buffer `out`. Values
+ * outside this range will produce an undefined encoding.
+ * `out` must point to at least 1 byte of space.
  *
- * out must point to at least 1 byte.
+ * Always writes a single byte.
+ *
+ * In a complete message stream, a size of N must be immediately followed by
+ * N other pairs of messages, each containing a key followed by a value, making
+ * up the contents of the map.
  *
  * It is recommended to use msg_putmsz() for arbitrary map sizes. That function
  * will produce the smallest possible encoding for any size value.
  */
-void msg_putmsz4(unsigned char *out, int sz);
+static inline void msg_putmsz4(unsigned char *out, int sz) {
+	*out = 0x80 | sz;
+}
 
 /*
- * Writes the array size sz in the range [0, 65536] to the buffer out.
+ * Writes the map size `sz` in the range [0, 15] immediately before the pointer
+ * `end`. Values outside this range will produce an undefined encoding.
+ *
+ * `end` must point immediately at least 1 byte of space.
+ *
+ * Always writes a single byte.
  *
  * In a complete message stream, a size of N must be immediately followed by
- * N * 2 other messages, which form the contents of the map as keys followed by
- * values in alternation.
+ * N other pairs of messages, each containing a key followed by a value, making
+ * up the contents of the map.
+ *
+ * It is recommended to use msg_rputmsz() for arbitrary map sizes. That function
+ * will produce the smallest possible encoding for any size value.
+ */
+static inline void msg_rputmsz4(unsigned char *end, int sz) {
+	end[-1] = 0x80 | sz;
+}
+
+/*
+ * Writes the map size `sz` in the range [0, 65536] to the buffer `out`.
  *
- * out must point to at least 3 bytes.
+ * `out` must point to at least 3 bytes of space.
  *
  * Returns the number of bytes written, one of {1, 3}.
  *
+ * In a complete message stream, a size of N must be immediately followed by
+ * N * 2 other messages, which form the contents of the map as alternating
+ * pairs, each containing one key followed by one value.
+ *
  * It is recommended to use msg_putmsz() for arbitrary map sizes. That function
  * will produce the smallest possible encoding for any size value.
  */
 int msg_putmsz16(unsigned char *out, int sz);
 
 /*
- * Writes the array size sz in the range [0, 4294967295] to the buffer out.
+ * Writes the map size `sz` in the range [0, 65536] immediately before the
+ * pointer `end`. Values outside this range will produce an undefined encoding.
+ *
+ * `end` must point immediately beyond least 3 bytes of space.
+ *
+ * Returns the number of bytes written, one of {1, 3}.
  *
  * In a complete message stream, a size of N must be immediately followed by
- * N * 2 other messages, which form the contents of the map as keys followed by
- * values in alternation.
+ * N other pairs of messages, each containing a key followed by a value, making
+ * up the contents of the map.
  *
- * out must point to at least 5 bytes.
+ * It is recommended to use msg_rputmsz() for arbitrary map sizes. That function
+ * will produce the smallest possible encoding for any size value.
+ */
+int msg_rputmsz16(unsigned char *end, int sz);
+
+/*
+ * Writes the map size `sz` in the range [0, 4294967295] to the buffer `out`.
+ *
+ * `out` must point to at least 5 bytes of space.
  *
  * Returns the number of bytes written, one of {1, 3, 5}.
+ *
+ * In a complete message stream, a size of N must be immediately followed by
+ * N other pairs of messages, each containing a key followed by a value, making
+ * up the contents of the map.
  */
 int msg_putmsz(unsigned char *out, unsigned int sz);
 
+/*
+ * Writes the map size `sz` in the range [0, 4294967295] immediately before the 
+ * pointer `end`.
+ *
+ * `end` must point immediately beyond at least 5 bytes of space.
+ *
+ * Returns the number of bytes written, one of {1, 3, 5}.
+ *
+ * In a complete message stream, a size of N must be immediately followed by
+ * N other pairs of messages, each containing a key followed by a value, making
+ * up the contents of the map.
+ */
+int msg_putmszr(unsigned char *end, unsigned int sz);
+
 #ifdef __cplusplus
 }
 #endif