MLib — Useful Standard Library Extensions
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

MLib is a collection of various headers and libraries that I find useful
in a large enough number of my personal C projects.  This includes for
example: common datastructures, useful non-POSIX APIs, and 21st-century
strings.

This does not aim to be a LibC replacement, but rather a supplimentary
library.  It is a C23 library with no plans to support older standards.

The headers as of now are:
 • alloc.h          — allocators and memory allocation functions
 • bitset.h         — bitset implementation
 • cli.h            — CLI-option parsing functions
 • dynarr.h         — dynamic array implementation
 • errors.h         — err.h-inspired diagnostics functions
 • macros.h         — miscellaneous utility macros (MIN/MAX/lengthof/etc.)
 • mbio.h           — multibyte file I/O
 • mbstring.h       — multibyte-strings
 • rune.h           — inttypes.h but for runes
 • unicode/prop.h   — unicode character properties
 • unicode/string.h — unicode string functions


BUILD INSTRUCTIONS:

    To build Mlib you need to have a C23 conforming C compiler.  Simply
    bootstrap the build system and run it:

        $ cc -o make make.c
        $ ./make

    To build with optimizations enabled, use the -r flag:

        $ ./make -r

    By default the build script will build a static library.  This can
    also be made explicit by passing the -a flag.  If you would like to
    instead build a shared-object library you may pass the -s flag:

        $ ./make -rs  # Build a shared-object with optimizations
        $ ./make -as  # Build a shared-object and static library


DISCLAIMER:

    This library is developed for use by me (the author).  You are free
    to use this code for whatever you’d like, but do be warned that
    breaking changes may (and will) occur at any moment with no prior
    warning.  Additionally, be warned that I do not care about whether or
    not you think the API is well-designed or human-friendly.  If you
    have an issue with the code here, fix it — you are a programmer are
    you not?


DOCUMENTATION:

    All headers, types, functions, etc. are documented in the manual
    pages found in the man/ subdirectory.  You can install these globally
    to your system by running the following:

        $ ./make manstall

    Some important manuals are:
    • mlib(7) — overview of the MLib library
    • ⟨header-name⟩.h(3) — overview of the ⟨header-name⟩.h header


FEATURES:

    The following is a non-exhaustive list of features.

    • alloc.h
        • Arena allocation functions
        • realloc() wrapper with overflow checking
        • realloc() wrapper with overflow checking that crashes on failure
        • Arena- and heap allocator functions to pass as callbacks to
          memory-allocating functions
    • bitset.h
        • Bitset implementation and operations
    • cli.h
        • Thread-safe (non-global) UTF-8-aware option parsing with
          support for short- and long options
    • dynarr.h
        • Dynamic-array implementation and operations
        • Macro for array iteration
    • errors.h
        • Functions for getting and setting the program name
        • Functions for printing diagnostics and optionally crashing with
          strerror() support
        • Generate usage strings
    • macros.h
        • MIN()/MAX()/CLAMP()
        • Better assertion macro
        • More readable strcmp()/memcmp()/etc. wrappers for equality
          checking
        • Static array length macro
        • STR() and CONCAT() to aid metaprogramming
    • mbio.h
        • Read individual runes from files
    • mbstring.h
        • Encode and decode runes
        • Encoding-generic macros (ucs*() instead of u8*())
        • Iterate over UTF-8 codepoints
        • Count UTF-8 codepoints
        • UTF-8 validation
        • Various string.h analogues with UTF-8 support
        • UTF-8 string cutting/splitting
        • Random utility macros and -constants
    • rune.h
        • Format string macros for the printf() and scanf() families of
          functions
        • Macro for defining rune constants
        • Useful rune-related constants
    • unicode/prop.h
        • Functions for getting Unicode character properties for runes
        • Properties related to case-mapping are context-aware (via a
          context-struct argument)
    • unicode/string.h
        • Case-mapping supports optional language-specific quirks for
          Azeri, Dutch, German, Lithuanian, and Turkish.
        • Encoding-generic macros (ucs*() instead of u8*())
        • Iteration and counting of graphemes, words, and human-precieved
          words in a string
        • NFC-, NFD-, NFKC-, and NFKD string normalization
        • Unicode-aware case-mapping of strings with custom allocator
          support


PLANNED FEATURES:

    • Line- and sentence segmentation            (unicode/string.h)
    • String collation                           (unicode/string.h)
    • Use gperf to generate hashtables for       (unicode/string.h)
      unicode composition?


BUGS:

    • Unicode Name Aliases (Name_Alias property) are not supported
    • Unihan properties are not supported (e.g. Unicode_Radical_Stroke)