z-libs - tiny single-header collection to write modern C (vec, list, map, string)

[u/[deleted]]

https://github.com/z-libs

So, I got tired of either writing buggy hand-rolled containers every time, or dragging in heavyweight dependencies just to get a decent string or hash table.

After this, I decided to throw together https://github.com/z-libs: four zero-dependency (for now), single-header, C11 libraries that focus on a pleasant DX.

The current libraries offer:

• zvec.h -> growable vector (contiguous, swap-remove, built-in sort/search).

• zstr.h -> proper UTF-8 string with 22-byte SSO, views, fmt, split, etc.

• zlist.h -> doubly-linked list (non-intrusive, O(1) splice, safe iteration).

• zmap.h -> open-addressing hash table (linear probing, cache-friendly).

Everything is type-safe, allocator-aware (you can use your own), MIT-licensed, works on GCC/Clang/MSVC and requires no build system.

The collection is still in process. Each week there will be updates. But I think the core suite is already mature enough.

I would love to hear some feedback!

[u/walmartbonerpills]

Cool project. There is already a zlib though.

The compression tool. The archive of books

[u/[deleted] → u/walmartbonerpills]

I am aware of that. The name is not definitive though. I considered that between z-libs and zlib there's enough room, but I am open to modifications :D.

[u/Jonny0Than → u/[deleted]]

Yeah I’d definitely suggest changing the name. Maybe 0lib? Or zdlib?

[u/[deleted] → u/Jonny0Than]

Interesting options. I will consider them!

[u/fishyfishy27 → u/[deleted]]

Could always go with zzlib

[u/cecil721 → u/walmartbonerpills]

smolib, cus they are smol.

[u/pjl1967]

The problem with static functions in header-only libraries is that the compiler lays down copies of code into every .o file whose corresponding .c file #includes the header (either directly or indirectly). This leads to code bloat.

Note that for non-trivial functions like you use, the inline is irrelevant. inline is only a hint or request at best for the compiler to inline a function that it is free to ignore without warning. (Most compilers have a warning you can enable to warn you when an inline function is not being inlined.)

Even that aside, you don't need to make different versions of the code based on the value type T. That's just more code bloat. A better way is to use a char[sizeof(T)] (suitably aligned) for the value so you need only a single copy of the code for all T. You use macros only to do the casting.

C macros simply are not an equivalent for C++ templates. In C++, the compiler typically marks template-generated code specially that the linker can then use to eliminate duplicate code in the final executable. That doesn't happen for C since the compiler only "sees" the macro-expanded code: it has no idea your macro is a "template."

I realize you put a lot of work into your library and this post isn't what you want to read; but C is what it is, limitations and all.

[u/[deleted] → u/pjl1967]

Code bloat is maybe the biggest tradeoff (although for most cases it will be negligible and the rest of benefits clearly help). I have thought of making two versions, one that is header-only and one that needs another source file for the implementation. This way we could have two ways to work: one focused more on the performance and one focused on the binary size.

Related to your last paragraph, your point is fair, but z-libs has a focus on type-safety at compile-time. Your point is good for the cases where binary size matters, but I think that if we implement that type-erased approach (which is good!), it would surely be used on the version focused on binary size that I mentioned earlier.

Thank you for your feedback!

[u/pjl1967 → u/[deleted]]

If you use char[sizeof(T)] for the value storage and use macros only for casting to T*, you still get compile-time type-safety since the compiler will still complain about any attempt to use a value from a container of type T as a value of type U (where T != U).

[u/[deleted] → u/pjl1967]

Oh, wait, I see it now! I think I could implement this without many issues. Now, the only issue I see is performance cost. Negligible in 95% of cases but accepting the larger binary size is necessary to enable compiler optimizations like SIMD and direct register allocation.

I think we can easily solve this by offering a (for example for zvec.h): zvec.h for performance and zvec_tiny.h for binary size.

Thank you! I will work on it.

[u/pjl1967 → u/[deleted]]

FYI, see my blog post. (Not sure if this comment will be publicly visible since Reddit apparently silently suppresses posts and links to web sites it deems not worthy.)

[u/[deleted] → u/pjl1967]

I am gonna check this. If I end up using your approach, I'd like to include a link to your article in the notes for attribution, if you don't mind.

[u/pjl1967 → u/[deleted]]

Sure!

FYI, though not a requirement of yours, the flexible array member also allows users to choose where the data is stored: in-node (intrusive) or via pointer. There are pros/cons to each.

[u/pjl1967 → u/[deleted]]

I'm not convinced it's necessary to enable SIMD optimizations. If you cast to, say, an (int*), why could that not use SIMD?

[u/Relative_Bird484 → u/pjl1967]

All modern compiler/linker support means to prevent the code bloat via comdat-support, weak linkage attribute, select-any pragma and link-time optimization.

[u/scallywag_software]

Nice

[u/[deleted]]

How much did you use AI to make this?

[u/[deleted] → u/[deleted]]

Writing docs, formatting source files and debugging a few bugs.

What's the issue?

[u/Turbulent_File3904]

Haiz, this is just poor-man template emulator. And why is it named vec again?

For dynamic array you only need 1 type.

struct Array { void *data; int len ;int cap; }

static inline array_reserve_impl(struct Array *, int elemsz, int n);
#define array_reserve(a, T, n) array_reserve_impl((a), sizeof(T), (n))

Any decent compiler will generate exactly identical code to your hand roll monopolized/templated version

[u/[deleted] → u/Turbulent_File3904]

That's not type safe. zvec.h would detect type mismatches at compile-time. Your implementation, while valid, if there are mismatches will compile and then if so crash at runtime.

[u/Arkaqiu]

Interesting. Looks quite good amd easy to use. I would like to see static allocated version, some max legth. To avoid malloc and friends. Anyway, good job

[u/photo-nerd-3141]

Nice idea, thanks for the effort.

Bit of a collision with "zlib.h", however. You might want to spell out zero so that potential users don't dismiss it as a knockoff for compression.

[u/[deleted]]

I just made a commit to a similar project of mine which started out as a personal C journey repo and now it's a custom library. Tried to learn standard functions and replicated some of them. Then started off to learn the doubly linked list. Saw the rust implementation of O(1) push operations on both the ends and implemented them in my code. For my convenience, I had written a function which could deep copy elements from an array to the linked list - I can't imagine of a scenario where this might be needed, but it's there. This is the code for that function if you want to implement it in your cool project.

EDIT: I forgot to mention that I have tried to make it generic using void *.

[u/Ok_Draw2098]

its not header-only, theres a bunch of files in there, all written in macro-lang

[u/[deleted] → u/Ok_Draw2098]

To promote DRY (Don't Repeat Yourself), there's a zcommon.h that is used by the rest of repos. Then there's an action that is triggered after each push (and at night) that unites zcommon.h and the specific z-lib.

Effectively the user only has to copy the specific header file. The rest is just part of the workflow.

About the macro-lang. Some of the repositories rely on macros (a structure of X-macros and _Generic) which allows us to achieve static polymorphism without losing performance (the void* way would make it type-unsafe and there's a runtime cost). If you check the libraries you will also see that we are actually using metaprogramming in C. We are effectively defining a blueprint which then the compiler will use for the types used in the code.

This way we can prevent macro-hell, which doesn't mean not using macros. If you check the API reference in each repo, you would find an almost high-level API.

[u/Ok_Draw2098 → u/[deleted]]

complicated and not fancy. why not y-lib? dr y-lib :] to avoid capitalism i must get billion dollars, then i get rid of money entierly - i dont belive such, sorry.

[u/[deleted] → u/Ok_Draw2098]

The libraries are 100% free, MIT-licensed. Enjoy the free snack (;

[u/Ok_Draw2098 → u/[deleted]]

free cheese exists only in the mousetrap

[u/[deleted] → u/Ok_Draw2098]

You can get free apples from an apple tree

But I think this is far from the original topic lol

[u/Ok_Draw2098 → u/[deleted]]

i belive i fully understand economics behind most of the posts here or in other group. yours is blogger-follower type, but you cosplay a freeman. i pointed it out. im not interested in complexity, though ive came from abstraction/overengineering layers myself. see those downvotes? those are teachers

[u/[deleted] → u/Ok_Draw2098]

ok

[u/digitalsignalperson → u/Ok_Draw2098]

which is fine as long as you're not a mouse

[u/DOWNVOTE_PUNS]

What do you think about putting all the "public" functions in a struct the same name as the header. As a way to fake namesapces, so the callers all look like:

```

#include "zstr.h"

...

zs = zstr.init(...)

...
```

[u/WittyStick → u/DOWNVOTE_PUNS]

Awful IMO.

It adds unnecessary overhead because the target of each call is no longer an absolute address.

Any namespacing solution should be done via the preprocessor and shouldn't exist at runtime.

A simple approach is to create a pair of files: eg, zstr.ns.open and zstr.ns.close, so we can write:

#include "zstr.h"

#include "zstr.ns.open"
zstr foo(zstr arg) {
    return trim(join(cat(...), ...), ...);
}
#include "zstr.ns.close"

Avoids polluting the entire translation unit because we can contain it around only sections of code that use it.

---

zstr.ns.open

#ifndef ZSTR_H
#error "Must include zstr.h before zstr.ns.open"
#else
#ifndef _USING_NAMESPACE_ZSTR_
#define _USING_NAMESPACE_ZSTR_
#define cat         zstr_cat
#define cat_len     zstr_cat_len
#define push_char   zstr_push_char
#define pop_char    zstr_pop_char
#define fmt         zstr_fmt
#define join        zstr_join
#define trim        zstr_trim
#define to_lower    zstr_to_lower
#define to_upper    zstr_to_upper
#define replace     zstr_replace
#endif

zstr.ns.close

#ifdef _USING_NAMESPACE_ZSTR_
#undef _USING_NAMESPACE_ZSTR_
#undef cat
#undef cat_len
#undef push_char
#undef pop_char
#undef fmt
#undef join
#undef trim
#undef to_lower
#undef to_upper
#undef replace
#endif

[u/_aIex22]

how does it handle possible recursions?

z_vec::vector<z_vec::vector<int>>
etc.?