AxlStr -- String Utilities
==========================

String utilities operating on UTF-8 ``char *`` strings. Includes length,
copy, compare, search, split, join, and case-insensitive operations (ASCII
fold only). UCS-2 helpers at the bottom are for UEFI internal use.

All allocated results are freed with ``axl_free()``.

Header: ``<axl/axl-str.h>``

Overview
--------

AXL uses UTF-8 (``char *``) throughout its public API. UEFI firmware
uses UCS-2 (``unsigned short *``) internally, but AXL handles the
conversion transparently -- you never need to deal with UCS-2 unless
making direct UEFI protocol calls.

UTF-8 vs UCS-2
~~~~~~~~~~~~~~~

- **Use UTF-8** (``char *``) for all application code. All ``axl_str*``
  functions operate on UTF-8.
- **UCS-2** functions (``axl_wcslen``, ``axl_wcscmp``, ``axl_str_to_w``,
  ``axl_str_from_w``) exist only for UEFI interop. Consumer code should
  not need them.

Case-Insensitive Operations
~~~~~~~~~~~~~~~~~~~~~~~~~~~

``axl_strcasecmp``, ``axl_strcasestr``, and ``axl_strncasecmp`` fold
**ASCII letters only** (A-Z → a-z). They do not handle full Unicode
case mapping. This is sufficient for UEFI identifiers, HTTP headers,
and file extensions.

Common Patterns
~~~~~~~~~~~~~~~

.. code-block:: c

   #include <axl.h>

   // Split a string
   char **parts = axl_strsplit("a,b,c", ',');
   for (int i = 0; parts[i] != NULL; i++) {
       axl_printf("  %s\n", parts[i]);
   }
   axl_strfreev(parts);  // frees the array AND each string

   // Join strings
   const char *items[] = {"one", "two", "three", NULL};
   char *joined = axl_strjoin(", ", items);
   axl_printf("%s\n", joined);  // "one, two, three"
   axl_free(joined);

   // Search
   if (axl_str_has_prefix(path, "fs0:")) { ... }
   if (axl_str_has_suffix(name, ".efi")) { ... }
   const char *found = axl_strcasestr(header, "content-type");

Memory Ownership
~~~~~~~~~~~~~~~~

Functions that return ``char *`` allocate new memory. The caller
must free with ``axl_free()``:

- ``axl_strdup``, ``axl_strndup``
- ``axl_strsplit`` (free with ``axl_strfreev``)
- ``axl_strjoin``, ``axl_strstrip``
- ``axl_str_to_w``, ``axl_str_from_w``

Functions that return ``const char *`` or ``char *`` pointing into
the input string do NOT allocate:

- ``axl_strstr_len``, ``axl_strrstr`` (return pointer into haystack)
- ``axl_strchr`` (return pointer into string)

API Reference
-------------

.. doxygenfile:: axl-str.h