From e99e1b5a8e3a06b8d7d2ba03d198e74f55f4f286 Mon Sep 17 00:00:00 2001 From: Konrad Malawski Date: Wed, 10 Dec 2025 18:07:53 +0900 Subject: [PATCH] SE-0498: clarify state of output span after truncated demangle --- proposals/0498-runtime-demangle.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/proposals/0498-runtime-demangle.md b/proposals/0498-runtime-demangle.md index 7468ea41f9..5be14a7f9a 100644 --- a/proposals/0498-runtime-demangle.md +++ b/proposals/0498-runtime-demangle.md @@ -55,9 +55,9 @@ The span accepting API is necessary for performance sensitive use-cases, which a The output from this API is an `OutputSpan` of `UTF8.CodeUnit`s, and it may not necessarily be well-formed UTF8, because of the potential of truncation happening between two code units which would render the UTF8 invalid. -If the demangled representation does not fit the preallocated buffer, the demangle method will return `truncated(actualSize)` such that developers can determine by how much the buffer might need to be increased to handle the complete demangling. +If the demangled representation does not fit the preallocated buffer, the demangle method will return `truncated(actualSize)` such that developers can determine by how much the buffer might need to be increased to handle the complete demangling. When `.truncated` is returned, the `OutputSpan` will contain a _partial result_, of however many characters were able to fit into it before truncation ocurred. This also means that a truncated output may not be entirely valid UTF8. -To construct an `UTF8Span` or valid `String` from the `OutputSpan` you can do the following: +Converting the outputSpan to a `String`, which is guarateed to be valid UTF8, follows the below pattern, where creating an `UTF8Span` _will_ perform validation of the UTF8 String contents, and fail if the output wasn't correct. ```swift var demangledOutputSpan: OutputSpan = ... @@ -69,6 +69,8 @@ if demangle("$sSG", into: &demangledOutputSpan) == .success { } ``` +As this example shows, the path to constructing a String is therefore safe, and we don't want to perform validation earlier during `demangle`, because you may want to store the exact bytes that were returned for some future processing. + ### Demangling format While the mangled strings are part of Swift ABI and can therefore not really change on platforms with stable ABI, the demangled representation returned by the `demangle` functions is _not guaranteed to be stable in any way_.