New upstream version 5.3upstream/5.3upstream

3 files changed, 72 insertions, 0 deletions

diff --git a/doc/api.rst b/doc/api.rst
index 332fca9..34006a0 100644
--- a/doc/api.rst
+++ b/doc/api.rst
@@ -9,6 +9,7 @@ Function reference
 ======  ======  ======  ========================================
 RMV     MinVer  FirstA  Name
 ======  ======  ======  ========================================
+5.3     5.3     5.3     HX::unique_tie
 5.0     5.0     4.28    HXdeque_to_vecx
 5.2     4.28    4.28    HX_getopt6
 4.28    4.28    4.28    HX_getopt6_clean
diff --git a/doc/changelog.rst b/doc/changelog.rst
index 6d399ae..2fd3b9b 100644
--- a/doc/changelog.rst
+++ b/doc/changelog.rst
@@ -1,3 +1,18 @@
+v5.3 (2026-01-29)
+=================
+
+Enhancements:
+
+* Added the ``<libHX/tie.hpp>`` include together with the
+  ``HX::unique_tie`` function
+
+Fixes:
+
+* Make ``HX_isascii`` work in C23 mode
+* Drop symbols from libHX.map that no longer exist,
+  these caused a build failure with llvm-ld (lld)
+
+
 v5.2 (2025-10-19)
 =================
 
diff --git a/doc/tie.rst b/doc/tie.rst
new file mode 100644
index 0000000..ba61dd7
--- /dev/null
+++ b/doc/tie.rst
@@ -0,0 +1,56 @@
+==============
+Memory helpers
+==============
+
+``unique_tie``
+==============
+
+``unique_tie`` creates a proxy object for ``std::unique_ptr<T,D>`` instances to
+interact with foreign functions that output a value through a ``T**`` pointer.
+
+Normally, for functions which return their result through an argument pointer,
+a temporary variable may be necessary when one wishes to use unique_ptr:
+
+.. code-block: c++
+
+	struct mydel { void operator()(void *x) const { free(x); } };
+
+	unique_ptr<char[], mydel> u;
+	char *x;
+	bla_alloc(&x);
+	u.reset(x);
+
+With ``unique_tie``, this can be shortened to:
+
+.. code-block: c++
+
+	unique_ptr<char[], mydel> u;
+	bla_alloc(&unique_tie(u));
+
+This is similar to C++23's ``std::out_ptr`` and ``std::in_out_ptr``.
+``unique_tie`` has subtle differences, though:
+
+* Only usable to ``unique_ptr``, not ``shared_ptr`` or raw pointers.
+* No implict conversions / No user-defined conversion operators.
+* No ``void **`` conversion.
+* Clearing is explicit, with ``~``.
+* Address-taking is explicit in text, i.e. you have to type a ``&`` in source
+  code. This is a deliberate choice for helping trivial text grepping for
+  pointer-taking.
+* There is higher memory use for when using a unique_ptr with custom deleter
+  function, but the optimizer might just optimize it away anyway.
+
+Repeated use of a variable with clearing inbetween works like so:
+
+.. code-block: c++
+
+	unique_ptr<char[], mydel> u;
+	iconvxx("utf-8", "utf-16", &unique_tie(u), srctext1);
+	printf("%s\n", u.get());
+	iconvxx("utf-8", "utf-16", &~unique_tie(u), srctext2);
+	printf("%s\n", u.get());
+	iconvxx("utf-8", "utf-16", &~unique_tie(u), srctext3);
+	printf("%s\n", u.get());
+
+It is acceptable to employ/enforce ``&~`` in all uses – even the
+first – of unique_tie in your project to guard against human error.