Skip to content

SE-0498: clarify state of output span after truncated demangle #3051

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ktoso wants to merge 1 commit into
base: main
Choose a base branch
from
Open

SE-0498: clarify state of output span after truncated demangle #3051

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions proposals/0498-runtime-demangle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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<UTF8.CodeUnit> = ...
Expand All @@ -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_.
Expand Down