What is it?
===========

This provides basic helper functions for C. It may include the following
categories of functions:

a) Portable versions of standard C functions, that can be used as drop-in
   replacements, with exactly the same semantics, excluding anti-features.

   You can alias these to standard C function names (with preprocessor macros,
   or even on the linker level).

b) Portable versions of standard C functions, with slightly different semantics,
   that can be used as drop-in replacements with some care. The semantics can
   be different to reduce annoying bugs, reduce dependencies and footprint, or
   because the standard functions are misdesigned.

   Depending on the details, you may alias them to standard function names, but
   with caveats you have to be aware of.

c) Like a) or b), but portability wrappers for crap OSes like Windows, Android,
   macOS, iOS, glibc-based Linux, etc.

d) Other helper functions.

Instead of standard C functions, they may be part of other standards, such as
POSIX.

Currently, only category b) wrappers for (v)snprintf and category a) wrappers
for strtod are provided.

Uses
====

- If your library uses libc functions affected by locale, like snprintf,
  strtod/strtol etc., but don't want your library to malfunction randomly if the
  library user sets the process locale. (The exact behavior of these libc
  functions will depend on your user's locale settings, usually the last thing
  you think about when analyzing bug reports.)
  Since you do not have control over this, replacing standard functions with
  mostly equivalent, but locale agnostic functions is the only reliable
  solution. Note that sometimes not even library users have control over this,
  since other libraries or plugins sometimes set locale.
- Ensuring true portability.
- Low footprint in bare metal environments or for small static executables
  (however, the focus is on correctness, not small code size).

How to use
==========

Currently, there are only test programs.

Conventions and rules
=====================

- Prefix all identifiers with lin_ or LIN_. (Exception: special include files
  that override standard C functions with category a) portable replacements,
  or macro-only identifiers in include files that specifically make non-prefixed
  identifiers visible.)
- Do not use any global mutable state.
- Do not override standard functions unless the user explicitly asks for it
  (i.e. don't be gnulib).
- Do not assume or hardcode implementation details of specific systems. One
  exception is when a known system requires workarounds for known standard
  violations. Code should work on arbitrary standard compliant systems.
- It's not a dumping ground for general utility functions (i.e. don't be glib).
- Try to reduce general entanglement within the library.
- No dependencies on broken libc mechanisms or types (such as locales, off_t).
- Avoid using: errno, stdio, malloc

Name
====

First I wanted to name it libsanity, because it was supposed to free programmers
from insanity like global locales. As a playful joke, it was named libinsanity.

Alternative solutions
=====================

You can just work around the traps set by these standard functions every time.
This library is supposed to spare you from this.

In the case of locale dependent functions, you could temporarily override the
current thread's uselocale(). But this is very inconvenient (you will likely
create wrappers anyway), and not available on all systems. On that note,
uselocale() is truly a bogus solution top the global locale problem. It's
literally the wrong way around, and per-thread state either requires pushing and
popping the state every time, or explicitly constraining code to dedicated
threads, both sub-optimal solutions for a problem that is purely created by the
standard committees.

You can use languages which have their own implementations of the same
mechanisms. So they will reimplement libc code or use any of the above
workarounds. Same difference if you reimplement it in a dedicated library.

License
=======

GNU ****** General Public License version 3. Most code is sourced from other
projects and copyrighted by their respective authors and contributors.