Keep a string
Most text in a zero-mode program lives somewhere short-lived: a line read into a stack buffer, a
string formatted in a scratch arena that is reset every round, the contents of a StrBuilder. To keep
one past that, copy it into an arena that lives as long as you need the text. This guide shows the
three ways to make that copy and how to collect the results.
Decide where the string will live
Create an arena for the lifetime of what you keep. The quiz keeps its mistakes until the end of the run, so it creates one arena for them, and the list that holds them lives there too:
// Lives until the end: the mistakes are kept here, the list and its strings.
Arena keep = Arena.Create(4096);
RefList<string> mistakes = RefList<string>.Create(keep);
if (!mistakes.IsCreated)
{
Out.Line("Arena.Create failed");
return 1;
}
RefList<string>.Create returns a not-created list if the arena couldn't be created or is full, which
IsCreated tells you.
Copy a span: Str.ToArenaString
A line from In.ReadLine is a slice of your buffer and is overwritten by the next read.
Str.ToArenaString(arena, span) copies it into a new string in the arena:
string kept = Str.ToArenaString(keep, buffer.Slice(0, length));
Any ReadOnlySpan<char> works, and a string converts to one implicitly, so the same call copies a
string out of an arena that is about to be reset.
Format straight into the long-lived arena: Str.Format
When the string you keep is formatted anyway, format it in the arena it will live in. No copy is needed:
else
{
Out.Line($"no, it's {a + b}");
// Kept until the end, so the string is built in `keep`, not in
// the buffer the next answer overwrites.
mistakes.Add(Str.Format(keep, $" {a} + {b} = {a + b}, not {value}"));
}
Str.Format(arena, $"...") builds the string in that arena and returns it. The holes are formatted
straight into arena memory (see Format text).
Build in scratch, keep only the result: StrBuilder.ToArenaString
A StrBuilder that grows can leave its old buffers behind in its arena until that arena is reset. Build
it in a scratch arena, copy the finished text into the arena that keeps it, and then reset or destroy
the scratch arena:
string kept = draft.ToArenaString(keep);
ToArenaString() without an argument copies into the builder's own arena. Both return null if the
arena is out of memory.
Collect the strings
List<T> takes only unmanaged types, so strings go in a RefList<string>, and foreach gives them
back:
Out.Line($"{right} of {asked} right");
if (mistakes.Count > 0)
{
Out.Line("Mistakes:");
foreach (string mistake in mistakes)
Out.Line(mistake);
}
A RefList stores references, not copies. The list can live in one arena and the strings in another,
but every string must outlive the list's use of it. A string built in a scratch arena dangles once
that arena is reset, even if the list lives elsewhere. RefDict<TKey, string> follows the same rule
for its values.
Keys are copied, values aren't
StrDict<TValue> looks up keys by their text and takes them as ReadOnlySpan<char>. A new key is
copied into the map's own arena, so a key read into a buffer that is then overwritten is safe. In
samples/Collections.cs, counts is a StrDict<int> and every word is copied into the same
8-character wordBuffer before it is counted:
foreach (ReadOnlySpan<char> w in "the cat and the hat and the bat".Split(' '))
{
for (int i = 0; i < w.Length; i++)
wordBuffer[i] = w[i];
ReadOnlySpan<char> key = wordBuffer.Slice(0, w.Length);
counts.TryGet(key, out int n);
counts.Set(key, n + 1);
}
The same holds for keys formatted in a scratch arena: the sample sets 500 keys made with
Str.Format(scratch, $"key{i}"), resetting scratch before each one, and later removes and finds
them by text with keys made the same way.
Values are stored as they are. A StrDict<string> holds references to its value strings, exactly like
RefList, so a value string must live as long as the map uses it:
var labels = StrDict<string>.Create(arena); // values can be references too
labels.Set("ok", "fine");
labels.Set("ok", Str.Format(arena, $"fine x{2}"));
Here the formatted value lives in the same arena as the map, so they go together. The literal "fine"
isn't in any arena, and the sample stores it directly.
Clone(target) on a StrDict copies the keys into the target arena too; values, again, are copied as
they are.
Watch out for
- Check for null when memory can run out.
Str.ToArenaString,Str.FormatandStr.Concatreturn null if the arena isn't created or is full. An arena created withstopOnOutOfMemory: trueends the program instead, so nothing needs checking (see Catch arena mistakes). a + bnever frees.+on strings allocates with calloc, and nothing is ever freed. That is fine once; in a loop, useStr.Concat(arena, a, b).- Freeing the arena frees the strings.
Restore,ResetandDestroyfree the strings in an arena along with everything else. Nothing reports a stale string afterwards: underArena.DebugChecksits memory reads0xDDbytes, but only collections check themselves. - A removed key's copy stays.
StrDict.Removeleaves the copied key in the arena until the arena is reset.
See also: Strings without a garbage collector,
Memory and arenas, the Str,
StrBuilder, RefList and
StrDict reference, and the tutorial's
Keep the mistakes.