Document library and common use cases

[jenspots]

Tools

• MkDocs Material

[jenspots]

By default, no types actually use the key/value paradigm, largely because it's redundant. Let's say we want to implement a structure alike Java's HashMap<Int, String>. A simple paradigm would be

#define LIBWHEEL_KEY   int
#define LIBWHEEL_VALUE char*
#define LIBWHEEL_ALIAS int2string

However, this brings quite a lot of complexity with it, mostly in terms of specific macros for this specific hashtable structure. Therefore, the following alternative is proposed.

typedef struct entry {
   int key;
   char* value;
}

#define LIBWHEEL_TYPE  entry
#define LIBWHEEL_ALIAS int2string

// Use only the key field when comparing instances.
int64_t compare(entry *a, entry *b) {
    return b->key - a->key;
}

Similarly, in libwheel, we always compute the hash value whenever it is required. It is never buffered. However, a user might decide to do so themselves.

typedef struct entry {
   int64_t hash_value;
   const char* string;
}

// User will compute hash manually and assign it to the field.
uint64_t hash(entry *e) {
    return e->hash_value;
}

The initialization function would then be something like

entry* entry_init(const char* s) {
    entry r = malloc(sizeof(entry));
    r->string = s;
    r->hash_value = desired_hash_function(s);
    return r;
}

Despite being somewhat more complex, these paradigms give users the greatest amount of freedom while being consistent as well.