buf.h (2686B)
1 #ifndef __FINWO_BUF_H__ 2 #define __FINWO_BUF_H__ 3 4 #ifdef __cplusplus 5 extern "C" { 6 #endif 7 8 /// finwo/buf 9 /// ========= 10 /// 11 /// > Simple byte buffers 12 /// 13 /// This library makes use of [dep](https://github.com/finwo/dep) to manage it's 14 /// dependencies and exports. 15 /// 16 /// Installation 17 /// ------------ 18 /// 19 /// ```sh 20 /// dep add finwo/buf 21 /// dep install 22 /// ``` 23 /// 24 /// After that, simply add `include lib/.dep/config.mk` in your makefile and include 25 /// the header file by adding `#include "finwo/buf.h`. 26 /// 27 28 #include <stddef.h> 29 30 /// API 31 /// --- 32 33 /// 34 /// ### Structures 35 /// 36 37 /// <details> 38 /// <summary>struct buf</summary> 39 /// 40 /// The main handle of the buffer library 41 ///<C 42 struct buf { 43 char *alloc; 44 char *dat; 45 size_t len; 46 size_t cap; 47 }; 48 ///> 49 /// </details> 50 51 /// 52 /// ### Methods 53 /// 54 55 /// <details> 56 /// <summary>buf_error(errno)</summary> 57 /// 58 /// Translates an error code into something human-readable (or null) 59 ///<C 60 const char *buf_error(int errno); 61 ///> 62 /// </details> 63 64 /// <details> 65 /// <summary>buf_append(subject, source, length)</summary> 66 /// 67 /// Append `length` bytes to the data in the buffer 68 /// Copies the data, does not mutate the source 69 /// 70 /// Returns an error code, or 0 on success 71 ///<C 72 int buf_append(struct buf *subject, const char *source, size_t length); 73 ///> 74 /// </details> 75 76 /// <details> 77 /// <summary>buf_append_byte(subject, value)</summary> 78 /// 79 /// Append a single byte to the buffer 80 /// 81 /// Returns an error code, or 0 on success 82 ///<C 83 int buf_append_byte(struct buf *subject, const char value); 84 ///> 85 /// </details> 86 87 88 /// <details> 89 /// <summary>buf_consume(subject, length)</summary> 90 /// 91 /// Remove `length` bytes from the front of the buffer 92 /// 93 /// Returns the amount of bytes removed (may differ from directive) 94 ///<C 95 size_t buf_consume(struct buf *subject, size_t length); 96 ///> 97 /// </details> 98 99 /// <details> 100 /// <summary>buf_clear(subject)</summary> 101 /// 102 /// Clears out all data from the buffer 103 ///<C 104 int buf_clear(struct buf *subject); 105 ///> 106 /// </details> 107 108 /** 109 */ 110 /// <details> 111 /// <summary>buf_set_allocator(realloc, free)</summary> 112 /// 113 /// Sets custom allocator instead of libc. This function, if needed, should be 114 /// called only once at startup and prior to calling buf_* functions 115 ///<C 116 void buf_set_allocator(void *(*realloc)(void*,size_t), void (*free)(void*)); 117 ///> 118 /// </details> 119 120 #ifdef __cplusplus 121 } // extern "C" 122 #endif 123 124 #endif // __FINWO_BUF_H__ 125 126 /// 127 /// Testing 128 /// ------- 129 /// 130 /// If you want to run the library's tests, simply run `make tests` to compile 131 /// and run the testing binaries 132 /// 133 /// License 134 /// ------- 135 /// 136 /// buf.c source code is available under the [FGPL License](License.md)