From 2dd4663ee68419059f327545e70095c4257b19e3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Frings-F=C3=BCrst?= Date: Tue, 10 Mar 2026 19:29:58 +0100 Subject: New upstream version 5.3 --- doc/tie.rst | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 doc/tie.rst (limited to 'doc/tie.rst') 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`` 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 u; + char *x; + bla_alloc(&x); + u.reset(x); + +With ``unique_tie``, this can be shortened to: + +.. code-block: c++ + + unique_ptr 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 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. -- cgit v1.2.3