commit cbc2a662b9f4adecd8f0ce80febf139381e6b7de
parent 867af93a9afeb2e9d2a6f240483852b3086df9d1
Author: finwo <finwo@pm.me>
Date: Sat, 18 Jul 2026 22:03:22 +0200
Add license and basic readme
Diffstat:
| A | LICENSE.md | | | 35 | +++++++++++++++++++++++++++++++++++ |
| M | Makefile | | | 3 | +++ |
| A | README.md | | | 121 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| M | src/buf.h | | | 122 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++------------- |
4 files changed, 262 insertions(+), 19 deletions(-)
diff --git a/LICENSE.md b/LICENSE.md
@@ -0,0 +1,35 @@
+Copyright (c) 2026 finwo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to use, copy,
+modify, and distribute the Software, subject to the following conditions:
+
+ 1. Redistributions of source code must retain the above copyright notice, this
+ list of conditions, and the following disclaimer.
+
+ 2. Redistributions in binary form, or any public offering of the Software
+ (including hosted or managed services), must reproduce the above copyright
+ notice, this list of conditions, and the following disclaimer in the
+ documentation and/or other materials provided.
+
+ 3. Any redistribution or public offering of the Software must clearly attribute
+ the Software to the original copyright holder, reference this License, and
+ include a link to the official project repository or website.
+
+ 4. The Software may not be renamed, rebranded, or marketed in a manner that
+ implies it is an independent or proprietary product. Derivative works must
+ clearly state that they are based on the Software.
+
+ 5. Modifications to copies of the Software must carry prominent notices stating
+ that changes were made, the nature of the modifications, and the date of the
+ modifications.
+
+Any violation of these conditions terminates the permissions granted herein.
+
+THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE COPYRIGHT
+HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
diff --git a/Makefile b/Makefile
@@ -16,3 +16,6 @@ tests: $(TESTS) ${TESTS:=.c}
.PHONY: clean
clean:
rm -f $(TESTS)
+
+README.md: src/buf.h
+ stddoc < src/buf.h > README.md
diff --git a/README.md b/README.md
@@ -0,0 +1,121 @@
+finwo/buf
+=========
+
+> Simple byte buffers
+
+This library makes use of [dep](https://github.com/finwo/dep) to manage it's
+dependencies and exports.
+
+Installation
+------------
+
+```sh
+dep add finwo/buf
+dep install
+```
+
+After that, simply add `include lib/.dep/config.mk` in your makefile and include
+the header file by adding `#include "finwo/buf.h`.
+
+API
+---
+
+### Structures
+
+<details>
+ <summary>struct buf</summary>
+
+ The main handle of the buffer library
+
+```C
+struct buf {
+ char *alloc;
+ char *dat;
+ size_t len;
+ size_t cap;
+};
+```
+
+</details>
+
+### Methods
+
+<details>
+ <summary>buf_error(errno)</summary>
+
+ Translates an error code into something human-readable (or null)
+
+```C
+const char *buf_error(int errno);
+```
+
+</details>
+<details>
+ <summary>buf_append(subject, source, length)</summary>
+
+ Append `length` bytes to the data in the buffer
+ Copies the data, does not mutate the source
+
+ Returns an error code, or 0 on success
+
+```C
+int buf_append(struct buf *subject, const char *source, size_t length);
+```
+
+</details>
+<details>
+ <summary>buf_append_byte(subject, value)</summary>
+
+ Append a single byte to the buffer
+
+ Returns an error code, or 0 on success
+
+```C
+int buf_append_byte(struct buf *subject, const char value);
+```
+
+</details>
+<details>
+ <summary>buf_consume(subject, length)</summary>
+
+ Remove `length` bytes from the front of the buffer
+
+ Returns the amount of bytes removed (may differ from directive)
+
+```C
+size_t buf_consume(struct buf *subject, size_t length);
+```
+
+</details>
+<details>
+ <summary>buf_clear(subject)</summary>
+
+ Clears out all data from the buffer
+
+```C
+int buf_clear(struct buf *subject);
+```
+
+</details>
+<details>
+ <summary>buf_set_allocator(realloc, free)</summary>
+
+ Sets custom allocator instead of libc. This function, if needed, should be
+ called only once at startup and prior to calling buf_* functions
+
+```C
+void buf_set_allocator(void *(*realloc)(void*,size_t), void (*free)(void*));
+```
+
+</details>
+
+Testing
+-------
+
+If you want to run the library's tests, simply run `make tests` to compile
+and run the testing binaries
+
+License
+-------
+
+buf.c source code is available under the [FGPL License](License.md)
diff --git a/src/buf.h b/src/buf.h
@@ -5,48 +5,132 @@
extern "C" {
#endif
+/// finwo/buf
+/// =========
+///
+/// > Simple byte buffers
+///
+/// This library makes use of [dep](https://github.com/finwo/dep) to manage it's
+/// dependencies and exports.
+///
+/// Installation
+/// ------------
+///
+/// ```sh
+/// dep add finwo/buf
+/// dep install
+/// ```
+///
+/// After that, simply add `include lib/.dep/config.mk` in your makefile and include
+/// the header file by adding `#include "finwo/buf.h`.
+///
+
#include <stddef.h>
+/// API
+/// ---
+
+///
+/// ### Structures
+///
+
+/// <details>
+/// <summary>struct buf</summary>
+///
+/// The main handle of the buffer library
+///<C
struct buf {
char *alloc;
char *dat;
size_t len;
size_t cap;
};
+///>
+/// </details>
-/**
- * Append <length> bytes to the data in the buffer
- * Copies the data, does not mutate the source
- *
- * Returns an error code, or 0 on success
- */
+///
+/// ### Methods
+///
+
+/// <details>
+/// <summary>buf_error(errno)</summary>
+///
+/// Translates an error code into something human-readable (or null)
+///<C
+const char *buf_error(int errno);
+///>
+/// </details>
+
+/// <details>
+/// <summary>buf_append(subject, source, length)</summary>
+///
+/// Append `length` bytes to the data in the buffer
+/// Copies the data, does not mutate the source
+///
+/// Returns an error code, or 0 on success
+///<C
int buf_append(struct buf *subject, const char *source, size_t length);
+///>
+/// </details>
-/**
- * Append single byte to the data in the buffer
- *
- * Returns an error code, or 0 on success
- */
+/// <details>
+/// <summary>buf_append_byte(subject, value)</summary>
+///
+/// Append a single byte to the buffer
+///
+/// Returns an error code, or 0 on success
+///<C
int buf_append_byte(struct buf *subject, const char value);
+///>
+/// </details>
-/**
- * Remove <length> bytes from the front of the buffer
- */
+
+/// <details>
+/// <summary>buf_consume(subject, length)</summary>
+///
+/// Remove `length` bytes from the front of the buffer
+///
+/// Returns the amount of bytes removed (may differ from directive)
+///<C
size_t buf_consume(struct buf *subject, size_t length);
+///>
+/// </details>
-/**
- * Clears out all data from the buffer
- */
+/// <details>
+/// <summary>buf_clear(subject)</summary>
+///
+/// Clears out all data from the buffer
+///<C
int buf_clear(struct buf *subject);
+///>
+/// </details>
/**
- * Sets custom allocator instead of libc. This function, if needed, should be
- * called only once at startup and prior to calling buf_* functions
*/
+/// <details>
+/// <summary>buf_set_allocator(realloc, free)</summary>
+///
+/// Sets custom allocator instead of libc. This function, if needed, should be
+/// called only once at startup and prior to calling buf_* functions
+///<C
void buf_set_allocator(void *(*realloc)(void*,size_t), void (*free)(void*));
+///>
+/// </details>
#ifdef __cplusplus
} // extern "C"
#endif
#endif // __FINWO_BUF_H__
+
+///
+/// Testing
+/// -------
+///
+/// If you want to run the library's tests, simply run `make tests` to compile
+/// and run the testing binaries
+///
+/// License
+/// -------
+///
+/// buf.c source code is available under the [FGPL License](License.md)
