From c4a491605510c925d1834e6cbb3cf31d619c8036 Mon Sep 17 00:00:00 2001
From: Calvin Rose <crose@gmail.com>
Date: Fri, 4 Dec 2020 17:56:47 -0600
Subject: [PATCH] Address #500 - update docs and add buffer/push

This updates the documentation and adds a function buffer/push, which
is a more useful function than buffer/push-string or buffer/push-byte by
combining both.
---
 src/core/buffer.c | 46 ++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 38 insertions(+), 8 deletions(-)

diff --git a/src/core/buffer.c b/src/core/buffer.c
index 6e040c00..9656b13a 100644
--- a/src/core/buffer.c
+++ b/src/core/buffer.c
@@ -256,6 +256,26 @@ static Janet cfun_buffer_chars(int32_t argc, Janet *argv) {
     return argv[0];
 }
 
+static Janet cfun_buffer_push(int32_t argc, Janet *argv) {
+    int32_t i;
+    janet_arity(argc, 1, -1);
+    JanetBuffer *buffer = janet_getbuffer(argv, 0);
+    for (i = 1; i < argc; i++) {
+        if (janet_checktype(argv[i], JANET_NUMBER)) {
+            janet_buffer_push_u8(buffer, (uint8_t)(janet_getinteger(argv, i) & 0xFF));
+        } else {
+            JanetByteView view = janet_getbytes(argv, i);
+            if (view.bytes == buffer->data) {
+                janet_buffer_ensure(buffer, buffer->count + view.len, 2);
+                view.bytes = buffer->data;
+            }
+            janet_buffer_push_bytes(buffer, view.bytes, view.len);
+        }
+    }
+    return argv[0];
+}
+
+
 static Janet cfun_buffer_clear(int32_t argc, Janet *argv) {
     janet_fixarity(argc, 1);
     JanetBuffer *buffer = janet_getbuffer(argv, 0);
@@ -407,22 +427,32 @@ static const JanetReg buffer_cfuns[] = {
     },
     {
         "buffer/push-byte", cfun_buffer_u8,
-        JDOC("(buffer/push-byte buffer x)\n\n"
-             "Append a byte to a buffer. Will expand the buffer as necessary. "
+        JDOC("(buffer/push-byte buffer & xs)\n\n"
+             "Append bytes to a buffer. Will expand the buffer as necessary. "
              "Returns the modified buffer. Will throw an error if the buffer overflows.")
     },
     {
         "buffer/push-word", cfun_buffer_word,
-        JDOC("(buffer/push-word buffer x)\n\n"
-             "Append a machine word to a buffer. The 4 bytes of the integer are appended "
-             "in twos complement, little endian order, unsigned. Returns the modified buffer. Will "
+        JDOC("(buffer/push-word buffer & xs)\n\n"
+             "Append machine words to a buffer. The 4 bytes of the integer are appended "
+             "in twos complement, little endian order, unsigned for all x. Returns the modified buffer. Will "
              "throw an error if the buffer overflows.")
     },
     {
         "buffer/push-string", cfun_buffer_chars,
-        JDOC("(buffer/push-string buffer str)\n\n"
-             "Push a string onto the end of a buffer. Non string values will be converted "
-             "to strings before being pushed. Returns the modified buffer. "
+        JDOC("(buffer/push-string buffer & xs)\n\n"
+             "Push byte sequences onto the end of a buffer. "
+             "Will accept any of strings, keywords, symbols, and buffers. "
+             "Returns the modified buffer. "
+             "Will throw an error if the buffer overflows.")
+    },
+    {
+        "buffer/push", cfun_buffer_push,
+        JDOC("(buffer/push buffer & xs)\n\n"
+             "Push both individual bytes and byte sequences to a buffer. For each x in xs, "
+             "push the byte if x is an integer, otherwise push the bytesequence to the buffer. "
+             "Thus, this function behaves like both `buffer/push-string` and `buffer/push-byte`. "
+             "Returns the modified buffer. "
              "Will throw an error if the buffer overflows.")
     },
     {