@@ -3,13 +3,16 @@
 
 ## 4.1.0 - 5th October 2026
 
-* Added 64-bit `djb2` hash functions: `cstring_hash_djb2()`, `cstring_hash_djb2_ci()`, `cstring_hash_djb2_len()`, and `cstring_hash_djb2_len_ci()`;
-* Added 64-bit `FNV-1a` hash functions: `cstring_hash_fnv1a()`, `cstring_hash_fnv1a_ci()`, `cstring_hash_fnv1a_len()`, and `cstring_hash_fnv1a_len_ci()`;
+* Added 64-bit `djb2` hash functions: `cstring_hash_djb2()`, `cstring_hash_djb2_case()`, `cstring_hash_djb2_buf()`, and `cstring_hash_djb2_buf_case()`;
+* Added 64-bit `FNV-1a` hash functions: `cstring_hash_fnv1a()`, `cstring_hash_fnv1a_case()`, `cstring_hash_fnv1a_buf()`, and `cstring_hash_fnv1a_buf_case()`;
+* Added multibyte and wide hash entry points `cstring_hash_djb2_mbs()`, `cstring_hash_djb2_wcs()`, `cstring_hash_djb2_mbuf()`, `cstring_hash_djb2_wbuf()`, and the `_case` forms, and the same set for `cstring_hash_fnv1a()`;
 * Added `cstring_hash_t` typedef (`uint64_t`);
-* Added C++ hash access shims for `cstring_t` (reference and pointer) and buffer/slice forms;
+* Added **common.h** for shared `<stdint.h>` discrimination, and **hash.h** for the hash API, included from **cstring.h**;
+* Added C++ hash access shims `hash_djb2()`, `hash_djb2_case()`, `hash_fnv1a()`, and `hash_fnv1a_case()` for `cstring_t` (reference and pointer), `char const*`, `wchar_t const*`, and both buffer forms;
 * Added unit test **test.unit.hash** (C hashing API, built with and without the C++ API) and **test.unit.hash.cxx** (C++ hash shims);
 * Published `CSTRING_HASH_DJB2_SEED`, `CSTRING_HASH_FNV1A_OFFSET`, and `CSTRING_HASH_FNV1A_PRIME` as the djb2 and FNV-1a basis constants;
 * Documented `CSTRING_HASH_DJB2_SEED`, `CSTRING_HASH_FNV1A_OFFSET`, and `CSTRING_HASH_FNV1A_PRIME` with references to the published djb2 and FNV-1a algorithms;
+* Documented the hash contract (forms, low octet, case fold, published vectors) and grouped the algorithms as `group__cstring_api__hashing__djb2` and `group__cstring_api__hashing__fnv1a`;
 
 
 ## 4.0.19 - 4th October 2026
 
@@ -46,7 +46,8 @@ See [INSTALL.md](./INSTALL.md) for details of how to install **cstring**.
 
 ## Q3: "How do I use cstring?"
 
-Include **cstring/cstring.h** (and **cstring/cstring.vector.h** where needed)
+Include **cstring/cstring.h** (which includes **cstring/hash.h**; and
+**cstring/cstring.vector.h** where needed)
 and link against **libcstring** (the **CMake** target is `cstring::core`).
 Create and destroy instances with `cstring_create()` / `cstring_destroy()`,
 and mutate with `cstring_assign()`, `cstring_append()`, and related APIs.
 
@@ -3,8 +3,8 @@
 **cstring** is a classic-form C library, insofar as it has implementation
 files in its **src** directory and header files in its **include/cstring**
 directory. Thus, once "installed", one must simply include
-**cstring/cstring.h** (and, where needed, **cstring/cstring.vector.h**), and
-compile-in or link-in the implementation.
+**cstring/cstring.h** (which includes **cstring/hash.h**) and, where needed,
+**cstring/cstring.vector.h**, and compile-in or link-in the implementation.
 
 The **C** API has no non-standard dependencies. Building the project's tests
 additionally requires **STLSoft** and **xTests** (and optionally recognises
@@ -164,10 +164,11 @@ The primary choice for installation is by use of **CMake**.
 In that case:
 
 * add **cstring**'s **include** directory to your project's include path;
-* compile **src/cstring.core.c** and **src/cstring.vector.c** into your build
-  (or link a previously built **libcstring**); and
+* compile **src/cstring.core.c**, **src/cstring.hash.c**, and
+  **src/cstring.vector.c** into your build (or link a previously built
+  **libcstring**); and
 * `#include <cstring/cstring.h>` (and **cstring/cstring.vector.h** where
-  needed).
+  needed). **cstring.h** includes **cstring/hash.h**.
 
 
 <!-- ########################### end of file ########################### -->
@@ -27,6 +27,8 @@ Small standalone C library that provides extensible C-style strings and extensib
     - [Modification functions](#modification-functions)
     - [File functions](#file-functions)
     - [Hashing functions](#hashing-functions)
+      - [djb2](#djb2)
+      - [FNV-1a](#fnv-1a)
   - [Vector API](#vector-api)
   - [C++ Integration](#c-integration)
 - [Examples](#examples)
@@ -215,16 +217,48 @@ Defined in **cstring/cstring.h**:
 
 #### Hashing functions
 
-Both 64-bit **djb2** (initial seed `5381`, `CSTRING_HASH_DJB2_SEED`) and **FNV-1a** (offset basis `0xcbf29ce484222325ULL`, `CSTRING_HASH_FNV1A_OFFSET`; prime `0x100000001b3ULL`, `CSTRING_HASH_FNV1A_PRIME`) hash functions are provided, returning `cstring_hash_t` (`uint64_t`). Buffer/slice variants (`_len`) allow hashing character sequences without constructing a `cstring_t` instance. Case-insensitive variants (`_ci`) fold characters to lower case, facilitating case-folded lookups and comparisons. All functions safely tolerate `NULL` pointers and zero lengths. An empty or `NULL` input hashes to `CSTRING_HASH_DJB2_SEED` or `CSTRING_HASH_FNV1A_OFFSET`:
+Declared in **cstring/hash.h**, which **cstring.h** includes. Both algorithms return `cstring_hash_t` (`uint64_t`). Multibyte and wide entry points exist in every build, whatever ambient `cstring_char_t` is. Each code unit contributes its low 8 bits, so ASCII text has one hash in both encodings. A wide code unit of value `0x161` hashes as the octet `0x61` (`'a'`). A `NULL` pointer, or a zero length, yields that algorithm's empty-input value and does not read the pointer.
 
-* `cstring_hash_djb2()` — calculates a 64-bit djb2 hash of a `cstring_t` instance;
-* `cstring_hash_djb2_ci()` — calculates a case-insensitive 64-bit djb2 hash of a `cstring_t` instance;
-* `cstring_hash_djb2_len()` — calculates a 64-bit djb2 hash of a character buffer or slice;
-* `cstring_hash_djb2_len_ci()` — calculates a case-insensitive 64-bit djb2 hash of a character buffer or slice;
-* `cstring_hash_fnv1a()` — calculates a 64-bit FNV-1a hash of a `cstring_t` instance;
-* `cstring_hash_fnv1a_ci()` — calculates a case-insensitive 64-bit FNV-1a hash of a `cstring_t` instance;
-* `cstring_hash_fnv1a_len()` — calculates a 64-bit FNV-1a hash of a character buffer or slice;
-* `cstring_hash_fnv1a_len_ci()` — calculates a case-insensitive 64-bit FNV-1a hash of a character buffer or slice;
+| Suffix | Input | What is hashed |
+| ------ | ----- | -------------- |
+| (none) | `cstring_t const*` | `ptr` for `len` code units, including embedded NULs |
+| `_mbs` | `char const*` | stops at the first NUL |
+| `_wcs` | `wchar_t const*` | stops at the first NUL |
+| `_buf` | `cstring_char_t const*`, `size_t` | ambient buffer; calls `_mbuf` or `_wbuf` |
+| `_mbuf` | `char const*`, `size_t` | exactly `cch` code units, including embedded NULs |
+| `_wbuf` | `wchar_t const*`, `size_t` | exactly `cch` code units, including embedded NULs |
+
+`_case` is the last suffix of each name (`cstring_hash_djb2_mbs_case()`, `cstring_hash_fnv1a_wbuf_case()`, and so on). Case folding uses `tolower` or `towlower`, which follow the process locale, and then the low 8 bits.
+
+Names follow `cstring_hash_<algorithm><suffix>`, for example `cstring_hash_djb2()`, `cstring_hash_djb2_mbuf()`, and `cstring_hash_fnv1a_wbuf_case()`.
+
+
+##### djb2
+
+The hash starts at `CSTRING_HASH_DJB2_SEED` (`5381`). For each octet `b` the step is `hash = ((hash << 5) + hash) + b`, which is `hash * 33 + b`. Daniel J. Bernstein's djb2, as published by Ozan Yigit.
+
+| Input | Hash |
+| ----- | ---- |
+| empty, or `NULL` | `5381` |
+| `"a"` | `177670` |
+| `"foobar"` | `6953516687550` |
+| `{ 'a', 0, 'b' }` length 3 | `193482728` |
+| octet `0xFF` | `177828` |
+
+The length-3 buffer differs from `"ab"`, because the embedded NUL is hashed.
+
+
+##### FNV-1a
+
+The hash starts at `CSTRING_HASH_FNV1A_OFFSET` (`0xcbf29ce484222325`). For each octet `b` the step is `hash ^= b` and then `hash *= CSTRING_HASH_FNV1A_PRIME` (`0x100000001b3`). Fowler, Noll, and Vo FNV-1a, 64-bit.
+
+| Input | Hash |
+| ----- | ---- |
+| empty, or `NULL` | `0xcbf29ce484222325` |
+| `"a"` | `0xaf63dc4c8601ec8c` |
+| `"foobar"` | `0x85944171f73967e8` |
+| `{ 'a', 0, 'b' }` length 3 | `0xe5d29919042666b2` |
+| octet `0xFF` | `0xaf64724c8602eb6e` |
 
 
 ### Vector API
@@ -244,7 +278,7 @@ Defined in **cstring/cstring.vector.h**:
 
 When included in C++ compilation units, **cstring/cstring.h** provides inline access shims:
 * **String access shims** — `c_str_data()`, `c_str_len()`, and `c_str_ptr()`, allowing `cstring_t` instances to be used directly with **STLSoft** and generic C++ templates;
-* **Hash access shims** — `hash_djb2()`, `hash_djb2_ci()`, `hash_fnv1a()`, and `hash_fnv1a_ci()`, overloaded for `struct cstring_t const&`, `struct cstring_t const*`, and slice / buffer forms `(cstring_char_t const* s, size_t cch)`;
+* **Hash access shims** — `cstring::hash_djb2()`, `cstring::hash_djb2_case()`, `cstring::hash_fnv1a()`, and `cstring::hash_fnv1a_case()`, overloaded for `struct cstring_t const&`, `struct cstring_t const*`, `char const*`, `wchar_t const*`, and the buffer forms `(char const* s, size_t cch)` and `(wchar_t const* s, size_t cch)`. A `NULL` argument must be cast, because `char const*` and `wchar_t const*` are both viable;
 
 
 ## Examples
@@ -299,11 +333,15 @@ When supplying `'--no-shwild'` — sets `NO_SHWILD=ON` — **shwild** is not rec
 
 ### Related projects
 
-Projects in which **cstring** is used include:
+Projects that call the **cstring** API, or that require the **CMake** package `cstring`:
 
-* [**errni**](https://github.com/sistools/errni)
-* [**rstrip**](https://github.com/sistools/rstrip)
-* [**shwild.fnmatch**](https://github.com/synesissoftware/shwild.fnmatch)
+| Project | Use |
+| ------- | --- |
+| [**errni**](https://github.com/sistools/errni) | Builds each result line and writes it with `cstring_writeline()` |
+| [**lnunique**](https://github.com/sistools/lnunique) | Requires `cstring` 4.0 and links `cstring::core` for line strings |
+| [**rstrip**](https://github.com/sistools/rstrip) | Accumulates each output line and writes it with `cstring_write()` |
+| [**shwild.fnmatch**](https://github.com/synesissoftware/shwild.fnmatch) | Holds patterns and subject strings as `cstring_t` |
+| [**STLSoft**](https://github.com/synesissoftware/STLSoft) | Optional; the C unit test `output_debug_line.C` uses `cstring_t` when the package is found |
 
 
 ### License
 
@@ -58,12 +58,18 @@
     * [ ] `--no-cpp`;
     * [ ] `--no-p99`;
     * [ ] `--no-shwild`;
+* [ ] API headers reconciled:
+  * [ ] String API in cstring/string.h;
+  * [ ] Hash API in cstring/hash.h;
+  * [ ] Vector API in cstring/vector.h;
+  * [ ] Umbrella / All API in cstring/cstring.h;
 * [-] ~~~Makefiles (legacy build trees removed; CMake-only)~~~ - ❌;
 * [ ] Packages:
   * [ ] vcpkg;
   * [ ] HomeBrew;
   * [ ] . . .
 * [ ] Website;
+* [ ] Project README.md and website need to mention clearly the provenance of the "auto-buffer" concept;
 * [ ] . . .
 
 
 
@@ -9,6 +9,9 @@ string instances and extensible arrays of such, for Unix and Windows.
 | Module | Header | Summary |
 | ------ | ------ | ------- |
 | @ref group__cstring_api | `<cstring/cstring.h>` | Core `cstring_t` API (create, mutate, stream I/O, status codes) |
+| @ref group__cstring_api__hashing | `<cstring/hash.h>` | djb2 and FNV-1a hashes of `cstring_t`, C strings, and buffers |
+| @ref group__cstring_api__hashing__djb2 | `<cstring/hash.h>` | djb2 (seed `5381`); instance, C string, and buffer forms |
+| @ref group__cstring_api__hashing__fnv1a | `<cstring/hash.h>` | FNV-1a 64-bit; the same forms as djb2 |
 | @ref group__cstring_api__flags | `<cstring/cstring.h>` | Memory-arena and capacity control flags |
 | Vector API | `<cstring/cstring.vector.h>` | `cstring_vector_t` sequences of `cstring_t` |
 
@@ -49,7 +52,15 @@ for build and install instructions.
 
 ## Related projects
 
-* [shwild.fnmatch](https://github.com/synesissoftware/shwild.fnmatch)
+Projects that call the **cstring** API, or that require the **CMake** package `cstring`:
+
+| Project | Use |
+| ------- | --- |
+| [errni](https://github.com/sistools/errni) | Builds each result line and writes it with `cstring_writeline()` |
+| [lnunique](https://github.com/sistools/lnunique) | Requires `cstring` 4.0 and links `cstring::core` for line strings |
+| [rstrip](https://github.com/sistools/rstrip) | Accumulates each output line and writes it with `cstring_write()` |
+| [shwild.fnmatch](https://github.com/synesissoftware/shwild.fnmatch) | Holds patterns and subject strings as `cstring_t` |
+| [STLSoft](https://github.com/synesissoftware/STLSoft) | Optional; the C unit test `output_debug_line.C` uses `cstring_t` when the package is found |
 
 
 <!-- ########################### end of file ########################### -->
@@ -0,0 +1,122 @@
+/* /////////////////////////////////////////////////////////////////////////
+ * File:    cstring/common.h
+ *
+ * Purpose: Common definitions for the cstring headers.
+ *
+ * Created: 5th October 2026
+ * Updated: 6th October 2026
+ *
+ * Home:    http://synesis.com.au/software/
+ *
+ * Copyright (c) 2026, Matthew Wilson and Synesis Information Systems
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ * - Redistributions of source code must retain the above copyright notice,
+ *   this list of conditions and the following disclaimer.
+ * - Redistributions in binary form must reproduce the above copyright
+ *   notice, this list of conditions and the following disclaimer in the
+ *   documentation and/or other materials provided with the distribution.
+ * - Neither the names of Matthew Wilson and Synesis Information Systems nor
+ *   the names of any contributors may be used to endorse or promote
+ *   products derived from this software without specific prior written
+ *   permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+ * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+ * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * ////////////////////////////////////////////////////////////////////// */
+
+
+/** \file cstring/common.h Common definitions for the cstring headers
+ */
+
+#ifndef CSTRING_INCL_CSTRING_H_COMMON
+#define CSTRING_INCL_CSTRING_H_COMMON
+
+
+/* /////////////////////////////////////////////////////////////////////////
+ * version
+ */
+
+#ifndef CSTRING_DOCUMENTATION_SKIP_SECTION
+# define CSTRING_VER_CSTRING_H_COMMON_MAJOR     1
+# define CSTRING_VER_CSTRING_H_COMMON_MINOR     0
+# define CSTRING_VER_CSTRING_H_COMMON_REVISION  1
+# define CSTRING_VER_CSTRING_H_COMMON_EDIT      1
+#endif /* !CSTRING_DOCUMENTATION_SKIP_SECTION */
+
+
+/* /////////////////////////////////////////////////////////////////////////
+ * includes
+ */
+
+#include <stddef.h>
+
+
+/* /////////////////////////////////////////////////////////////////////////
+ * compatibility
+ */
+
+/* Shared detection of <stdint.h>, used by cstring/hash.h when selecting the
+ * type of cstring_hash_t.
+ */
+
+#if 0
+#elif defined(__STDC_VERSION__) &&\
+      __STDC_VERSION__ >= 199901L
+
+# define CSTRING_HAS_h_stdint_
+#elif defined(__cplusplus) &&\
+      defined(__has_include) &&\
+      __has_include(<stdint.h>)
+
+# define CSTRING_HAS_h_stdint_
+#elif defined(__cplusplus) &&\
+      __cplusplus >= 201103L
+
+# define CSTRING_HAS_h_stdint_
+#elif 0 ||\
+      (   defined(_MSC_VER) &&\
+          _MSC_VER >= 1310) ||\
+      0
+
+# define CSTRING_HAS_h_stdint_
+#else
+
+#endif
+
+
+/* /////////////////////////////////////////////////////////////////////////
+ * includes
+ */
+
+#ifdef CSTRING_HAS_h_stdint_
+# include <stdint.h>
+#endif /* CSTRING_HAS_h_stdint_ */
+
+
+/* /////////////////////////////////////////////////////////////////////////
+ * inclusion control
+ */
+
+#ifdef STLSOFT_PPF_pragma_once_SUPPORT
+# pragma once
+#endif /* STLSOFT_PPF_pragma_once_SUPPORT */
+
+#endif /* CSTRING_INCL_CSTRING_H_COMMON */
+
+/* ///////////////////////////// end of file //////////////////////////// */
+