ref: 4eee9384335369b90b6311c1b2ddfa0cc25fa477
dir: /thirdparty/oso.h/
#pragma once // Heap-allocated string handling. // Inspired by antirez's sds and gingerBill's gb_string.h. // // "I need null-terminated strings to interact with libc and/or POSIX, and my // software isn't serious enough to warrant using arena or page allocation // strategies. Manually fussing with null-terminated strings with libc sucks, // even though we're allocating everything individually on the heap! Why can't // we at least get a nicer interface for the trade-off we've already made?" // // EXAMPLE // --------- // oso *mystring = NULL; // osoput(&mystring, "Hello World"); // printf((char *)mystring); // osoput(&mystring, "How about some pancakes?"); // printf((char *)mystring); // osocat(&mstring, " Sure!"); // printf((char *)mystring); // osofree(mystring); // // > Hello World! // > How about some pancakes? // > How about some pancakes? Sure! // // RULES // ------- // 1. `oso *` can always be cast to `char *`, but it's your job to check if // it's null before passing it to on something that doesn't tolerate null // pointers. // // 2. The functions defined in this header tolerate null pointers like this: // // `oso *` -> OK to be null. // `char const *` -> Must not be null. // `oso **` -> Must not be null, but the `oso *` pointed to // can be null. The pointed-to `oso *` may be // modified during the call. // // 3. `oso *` and `char const *` as arguments to the functions here must not // overlap in memory. During the call, the buffer pointed to by a `oso *` // might need to be reallocated in memory to make room for the `char const // *` contents, and if the `char const *` contents end up being moved by // that operation, the pointer will no longer be pointing at valid memory. // (This also applies to functions which accept two `oso *` as inputs.) // // Parameters with the type `oso *` are safe to pass as a null pointer. But // `oso **` parameters shouldn't be null. The `oso *` pointed to by the `oso // **` can be null, though. In other words, you need to do `&mystring` to pass // a `oso **` argument. // // During the function call, if the `oso *` pointed to by the `oso **` needs to // become non-null, or if the existing buffer needs to be moved to grow larger, // the `oso *` will be set to a new value. // // oso *mystring = NULL; // osolen(mystring); // Gives 0 // osocat(&mystring, "waffles"); // osolen(mystring); // Gives 7 // osofree(mystring); // // NAMES // ------- // osoput______ -> Copy a string into an oso string. // osocat______ -> Append a string onto the end of an oso string. // ______len -> Do it with an explicit length argument, so the C-string // doesn't have to be '\0'-terminated. // ______oso -> Do it with a second oso string. // ______printf -> Do it by using printf. // // ALLOC FAILURE // --------------- // If an allocation fails (including failing to reallocate) the `oso *` will be // set to null. If you decide to handle memory allocation failures, you'll need // to check for that. // // In the oso code, if a reallocation of an existing buffer fails (`realloc()` // returns null) then the old, still-valid buffer is immediately freed. // Therefore, in an out-of-memory situation, it's possible that you will *lose* // your strings without getting a chance to do something with the old buffers. // // Variations of the oso functions may be added in the future, with a _c suffix // or something, which preserve the old buffer and return an error code in the // event of a reallocation failure. I'm not sure how important this is, since // most existing libc-based software doesn't handle out-of-memory conditions // for small strings without imploding. // // (sds, for example, will lose your string *and* leak the old buffer if a // reallocation fails.) #include <stdarg.h> #include <stddef.h> #if (defined(__GNUC__) || defined(__clang__)) && defined(__has_attribute) #if __has_attribute(format) #define OSO_PRINTF(...) __attribute__((format(printf, __VA_ARGS__))) #endif #if __has_attribute(nonnull) #define OSO_NONNULL(...) __attribute__((nonnull(__VA_ARGS__))) #endif #endif #ifndef OSO_PRINTF #define OSO_PRINTF(...) #endif #ifndef OSO_NONNULL #define OSO_NONNULL(...) #endif typedef struct oso oso; #define osoc(s) ((char const *)s) void osoput(oso **p, char const *cstr) OSO_NONNULL(); // ^- Copies the '\0'-terminated string into the `oso *` string located at // `*p`. If `*p` is null or there isn't enough capacity to hold `cstr`, it // will be reallocated. The pointer value at `*p` will be updated if // necessary. `*p` and `cstr` must not point to overlapping memory. void osoputlen(oso **p, char const *cstr, size_t len) OSO_NONNULL(); // ^- Same as above, but uses an additional parameter that specifies the length // of `cstr, and `cstr` does not have to be '\0'-terminated. // `*p` and `cstr` must not point to overlapping memory. void osoputoso(oso **p, oso const *other) OSO_NONNULL(1); // ^- Same as above, but using another `oso`. `*p` and `other` must not point // to overlapping memory. void osoputvprintf(oso **p, char const *fmt, va_list ap) OSO_NONNULL(1, 2) OSO_PRINTF(2, 0); void osoputprintf(oso **p, char const *fmt, ...) OSO_NONNULL(1, 2) OSO_PRINTF(2, 3); // ^- Same as above, but do it by using printf. void osocat(oso **p, char const *cstr) OSO_NONNULL(); void osocatlen(oso **p, char const *cstr, size_t len) OSO_NONNULL(); void osocatoso(oso **p, oso const *other) OSO_NONNULL(1); void osocatvprintf(oso **p, char const *fmt, va_list ap) OSO_NONNULL(1, 2) OSO_PRINTF(2, 0); void osocatprintf(oso **p, char const *fmt, ...) OSO_NONNULL(1, 2) OSO_PRINTF(2, 3); // ^- Append string to oso string. Same rules as `osoput` family. void osoensurecap(oso **p, size_t cap) OSO_NONNULL(); // ^- Ensure that s has at least `cap` memory allocated for it. This does not // care about the strlen of the characters or the prefixed length count -- // only the backing memory allocation. void osomakeroomfor(oso **p, size_t len) OSO_NONNULL(); // ^- Ensure that s has enough allocated space after the '\0'-terminnation // character to hold an additional add_len characters. It does not adjust // the `length` number value, only the capacity, if necessary. // // Both `osoensurecap()` and `osomakeroomfor()` can be used to avoid making // multiple smaller reallactions as the string grows in the future. You can // also use them if you're going to modify the string buffer manually in // your own code, and need to create some space in the buffer. void osoclear(oso **p) OSO_NONNULL(); // ^- Set len to 0, write '\0' at pos 0. Leaves allocated memory in place. void osofree(oso *s); // ^- You know. And calling with null is allowed. void osowipe(oso **p) OSO_NONNULL(); // ^- It's like `osofree()`, except you give it a ptr-to-ptr, and it also sets // `*p` to null for you when it's done freeing the memory. void ososwap(oso **a, oso **b) OSO_NONNULL(); // ^- Swaps the two pointers. Yeah, that's all it does. Why? Because it's // common when dealing memory management for individually allocated strings // and changing between old and new string values. void osopokelen(oso *s, size_t len) OSO_NONNULL(); // ^- Manually updates length field. Doesn't do anything else for you. size_t osolen(oso const *s); // ^- Bytes in use by the string (not including the '\0' character.) size_t osocap(oso const *s); // ^- Bytes allocated on heap (not including the '\0' terminator.) void osolencap(oso const *s, size_t *out_len, size_t *out_cap) OSO_NONNULL(2, 3); // ^- Get both the len and the cap in one call. size_t osoavail(oso const *s); // ^- osocap(s) - osolen(s) void osotrim(oso *restrict s, char const *restrict cut_set) OSO_NONNULL(2); // ^- Remove the characters in `cut_set` from the beginning and ending of `s`. #undef OSO_PRINTF #undef OSO_NONNULL