Text, Subtext and the Sixteen Byte Problem

The desire

This is the follow on from my post on conversions when inherited and a constructor. The desire has not changed. I want a small text class that can be moved around by value, and I want one set of functions to work on it whether the text is owned or borrowed.

In my library there are now two types. A text_c owns its bytes on the UTF-8 heap. A subtext_c is a slice of a text, or a borrowed u8"" literal, and owns nothing. Both are a pointer, a size and a capacity, 16 bytes, and both are always NFC.

class text_c final
{
public:
    const char8_t* const    pointer;
    const u32               size;
    const u32               capacity;
    ...
};

class subtext_c
{
public:
    const char8_t* const    pointer;
    const u32               size;
    const u32               capacity{0};
    ...
};

The same bytes, the same layout. So surely writeUpper() or find() can take either one without me writing everything twice? That is the question this post follows, each attempt, with the issue that blocked each one. This was done with Claude (Opus 5.5 Medium) pointing out the pros and cons of each option.

Moving the data with casts

The first instinct was the C one. The bytes are the same, so just look at them as the other type.

My earlier post goes through some of this, using a union of span and block types. This used non standard extensions: nameless struct/union. The next was a conversion operator that returns a reference. No copy at all, just the address of the object seen as the other type. This leads to memory aliasing and while MSVC does not actually alias other compilers did.

Go for simple

I wrote down some options:

  1. Template all the functions. Cute, but increases compile time and code size.
  2. Use a struct conversion operator. Not allowed by the standard; you can only do struct pointers.
  3. A union, an anonymous struct and a conversion operator. Works, but not legal C++17, and it ties the heap block to the same layout.
  4. Give the heap block, text_c and subtext_c the same three members. A slice carries a capacity of zero, as it owns nothing.
  5. Move the data around between text and subtext. This seems very wasteful.

So I chose 4, as it is the simplest code and explored the impacts of that., Each class declares its own read functions, and they all call the same internal helpers on (utf8span_s)*this. A slice is 16 bytes, not 12, and I can live with that.

Blocked by: nothing, but it left a gap. The functions that take a second text still only took const text_c&: the find() needle, writeUpper(), writeLower(), writeTitle(), writeFold() and equalsIgnoringCase(). And text_c == subtext_c did not compile.

Make text to subtext implicit

There is already an explicit operator subtext_c() on text_c. Drop the explicit, make every read-only parameter a subtext_c, and a text just converts.

Blocked by: a pile of small surprises that Claude helped point out:

  • A slice taken from a temporary text dangles the moment the statement ends.
  • A literal passed for a text parameter used to be imported and normalised. It is now a subtext it is borrowed, so a non-NFC literal becomes a fault instead.
  • Hidden friend == lookup and overloads that take both types start to clash or go ambiguous.
  • You can no longer see at the call whether something owns its bytes.

Pass the subtext by value

My thinking was that copying a pointer and a size is free. Claude first said coping the subtext was the same cost as a reference. I did not buy it, and I was right.

On Windows x64 a struct is only passed in a register when it is 1, 2, 4 or 8 bytes. A 16 byte subtext_c is copied by the caller into a temporary on its stack, and the address of that copy is passed. A const text_c& passes the address of the text itself.

CallerCallee
const text_c&address in a registerreads [rcx] and [rcx+8]
subtext_c by valuethree stores to a stack copy, then its addressreads [rcx] and [rcx+8]

Blocked by: it is strictly more work than the reference. Small, but it is in the wrong direction. Taking a const subtext_c& does not help either, as a text still has to be turned into a temporary subtext for the reference to point at.

Hand back the text as a subtext reference

The layouts match, so the conversion could return the text itself:

operator const subtext_c&() const { return *(const subtext_c*)this; }

Blocked by: this is the reference cast from before. Strict aliasing again. I am not going full circle.

Two versions of each function and a core

One overload takes const text_c&, one takes subtext_c, and both call a core in core.cpp that takes the pointer and size as two plain parameters, so they go in registers.

Blocked by: literals. Both text_c and subtext_c can be built from a const char8_t* without asking, so writeUpper(u8"abc") matches both overloads and is ambiguous. Two argument functions like equalsIgnoringCase() also explode into four, and more with literals.

An internal view struct

Claude also suggested a private _textView_s of just pointer and size, with implicit conversions from a text and a subtext. One function per name, and the implicit conversion is hidden inside a type nobody stores.

Blocked by: it is still 16 bytes, so it still goes through a stack copy unless inlined. And a literal can no longer be imported: literal to text_c to view is two user defined conversions, which C++ does not allow, and a view cannot own an imported text anyway. It is also adding too much complexity. I did not like this one at all.

The scorecard

AttemptBlocked by
Union with an anonymous structnot legal C++; undefined behaviour
Conversion operator returning a referencestrict aliasing on other compilers
Same three-member layoutworked; left text-only parameters
Implicit text to subtextdangling slices, literal faults, ambiguity
Subtext by valuestack copy on Windows x64
Aliasing reference againstrict aliasing, again
Overloads and a coreliteral ambiguity, overload explosion
Internal view structstill 16 bytes; cannot import a literal

Back to templates

Option 1, the one I called cute, turned out to be the answer. Not templating the work, just a thin inline wrapper over one core. The wrapper is inlined at the call, so it costs nothing, and it reads the pointer and size straight out of whatever it was given.

What counts as a text argument

The trick that makes it safe is a forwarding reference. With T&&, const survives deduction, so after removeReference_ a u8"abc" is a const char8_t[4] and a buffer you filled is a char8_t[256]. Only the first is a literal.

template <typename type_t> inline constexpr b8 _isLiteralType = false;
template <u32 countBytes> inline constexpr b8 _isLiteralType<const char8_t[countBytes]> = true;
template <typename type_t> inline constexpr b8 _isTextType = false;
template <> inline constexpr b8 _isTextType<text_c> = true;
template <> inline constexpr b8 _isTextType<const text_c> = true;
template <> inline constexpr b8 _isTextType<subtext_c> = true;
template <> inline constexpr b8 _isTextType<const subtext_c> = true;
template <typename argument_t> inline constexpr b8 _isLiteral = _isLiteralType<typename removeReference_<argument_t>::type>;
template <typename argument_t> inline constexpr b8 _isTextArgument = (_isLiteral<argument_t> || _isTextType<typename removeReference_<argument_t>::type>);

Literals are borrowed, sized when it compiles

The subtext_c pointer constructor is gone. In its place is one that only takes a literal, and knows its size from the array, so there is no lstrlenA().

template <u32 countBytes> subtext_c(const char8_t (&literal)[countBytes]) : subtext_c{_fromLiteral(literal, countBytes - 1)} {}
template <u32 countBytes> subtext_c(char8_t (&buffer)[countBytes]) = delete;

If you made the string yourself, you import it with text_c{buffer}. A borrow can not normalise, as it can not own anything, so runtime data has to come in through the import.

One wrapper per function

template <utf8case_e mapping, typename source_t>
inline text_c _writeCaseOf(source_t&& source)
{
    if constexpr (_isLiteral<source_t>)
    {
        subtext_c literal{source};
        return text_c::_writeCase(literal.pointer, literal.size, mapping);
    }
    else
    {
        return text_c::_writeCase(source.pointer, source.size, mapping);
    }
}

template <typename source_t> requires _isTextArgument<source_t>
inline text_c writeUpper(source_t&& source) { return _writeCaseOf<utf8case_e::upper>(source); }

The core function are more explicit and take the pointer and size as two parameters. Not a span, as a span is 16 bytes and would bring the stack copy straight back. I had forgotten that was the reason, which is partly why this post exists.

equalsIgnoringCase() did not even need a core. writeFold() already takes any of the three:

template <typename a_t, typename b_t> requires (_isTextArgument<a_t> && _isTextArgument<b_t>)
inline b8 equalsIgnoringCase(a_t&& a, b_t&& b) { return (writeFold(a) == writeFold(b)); }

== written out by hand

A template == would join in on far more comparisons than I want, so it is the one exception. C++20 tries b == a as well as a == b, so five overloads cover every pair: text and text, subtext and subtext, text and subtext, text and literal, subtext and literal. The literal ones are not optional. Without them text == u8"x" is ambiguous between importing and borrowing.

What the compiler now refuses

CallError
find() or writeUpper() with a buffer or a pointerno matching overload
subtext_c{buffer}deleted constructor
slice == buffer, either way rounddeleted constructor
slice == pointerno operator found
text == bufferambiguous

What MSVC actually made

I asked Claude to compare the asm, which I would normally do, but I take ages to do so.

The old writeUpper(const text_c&) was two calls deep:

; master: probeUpperText
call    ?writeUpper@@YA?AVtext_c@@AEBV1@@Z    ; writeUpper, which then calls _writeCase

The template is inlined, so a text goes straight to the internal function with two loads and no stores. A subtext is exactly the same code:

; prototype: probeUpperText and probeUpperSubtext
mov     r8d, DWORD PTR [rdx+8]                 ; size
xor     r9d, r9d                               ; utf8case_e::upper
mov     rdx, QWORD PTR [rdx]                   ; pointer
mov     rbx, rcx
call    ?_writeCase@text_c@@SA?AV1@PEB_QIW4utf8case_e@@@Z
CallBeforeAfter
writeUpper(text)call writeUpper, which calls _writeCasetwo loads, one call to _writeCase
writeUpper(subtext)did not compilesame as a text
writeUpper(u8"abc")construct a text_c (allocate, import, NFC), call, destroy_fromLiteral with size 3 as a constant, then _writeCase
find(text)6 stores for two span copies, call _findfour loads to registers, 2 stores, call _find
find(subtext)did not compilesame as a text
find(u8"abc")construct, 6 stores, call, destroy_fromLiteral, 2 stores, call

The surprise was find(). _find is marked inline but MSVC chose not to inline it, so on the first build both its span arguments still went through stack copies. That is the 16 byte problem again, one level down, and it was there before I started. So _find now takes pointers and sizes too. Only four arguments fit in registers on Windows x64, so the needle size and the start letter still go on the stack, but that is 2 stores instead of 6. The body of _find came out 11 instructions shorter as well.

The literal check also still runs every call. ASCII is a quick scan, but a non-ASCII literal allocates scratch space to prove it is NFC.

Where that leaves it

It is not perfect, but it is a good solution and any remaining downsides I think I can accept. There is no aliasing, no implicit conversion in the public interface, one function per name, and literals are cheaper than they were. The call to an internal function is now a couple of register loads.

What is left in the downsides list:

  • text == pointer still compiles, as the text_c(const char8_t*) import is still implicit. Making it explicit would also break text + u8"...". (This was fixed in later iterations. Using explicit means text_c example = u8"not OK" will fail, but that is better than allowing the silent import for f(u8"copy this now")).
  • operator+ still takes two texts. (This was fixed in later iterations).
  • _find still builds a 16 byte span for every call to utf8letterBytes_() inside its loop. Same problem, one more level down, in utf8.h.
  • A non-ASCII literal is checked for NFC on every call.

The lesson for me is the same one as the last post. C++ will not let you say “these bytes are also that type”, however true it is. So you either copy, or you template. Copying 16 bytes turned out to be a real cost on Windows x64, so templates it is, kept as thin as I can make them.

C Strings in C++ and Deep Copies

I was told on Stack Overflow:

“A pointer is just a pointer.”

And that is true of course. To go beyond that we have structures and classes which have explicit construction and operators. However, C++ has inherited C strings which are just a pointer to the first char, but they also have a long history where the construction and operations are well known. So, when a C String is given to a map or vector, it may be thought that it could be doing a deep copy. After all, it is known (by implicit rules) how this could be completed. The size is defined. It is just not stored. Also, the storage is clear – just not managed.

Continue reading “C Strings in C++ and Deep Copies”