1 files changed, 56 insertions, 0 deletions
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.