BiffSstReader Struct
Definition
Reads the strings of a BIFF8 shared string table (SST) one at a time, pulling the CONTINUE records
that carry the table's overflow from the parent BiffReader as they are needed.
public ref struct BiffSstReader
- Inherited Members
Remarks
The reader is created while the parent is positioned on the SST record; each call to
Read(scoped ref BiffReader) is passed the parent by reference and advances it past every CONTINUE
record it consumes, so the parent's BytesConsumed stays truthful and the next
Read() resumes after the table. A ref struct cannot hold a reference to
another, which is why the parent is supplied per call rather than captured. It follows the BIFF continuation rules
for strings: a string's header never straddles a boundary, character data may, and a continued run restarts with its
own option-flags byte selecting 8-bit or 16-bit characters. A continuation record that holds only that flags byte
contributes no characters, and the string goes on in the next continuation record, whose own flags byte applies.
The table ends where its records end. Some producers declare more unique strings than the table holds, so when the
last of its records is exhausted at a string boundary and no CONTINUE record follows,
Read(scoped ref BiffReader) returns false even before
UniqueCount strings have been read. A string cut off inside its header or its
characters is malformed.
A string whose characters lie within one record is exposed as a span-backed Current view. A string whose characters straddle a boundary (IsFragmented) has no single span; it is decoded into a reusable scratch buffer during Read(scoped ref BiffReader), and GetString() and CopyTo(Span<char>) serve both kinds uniformly. Its code units are gathered from every segment before they are decoded, so a surrogate pair split between two segments decodes to its character, and a surrogate without its partner to U+FFFD, exactly as the same code units in one record do. Formatting-run and extended-data trailers that straddle a boundary are skipped and reported as empty.
while (reader.Read())
{
if (reader.RecordType != BiffRecordType.Sst)
continue;
var strings = new BiffSstReader(ref reader);
while (strings.Read(ref reader))
Console.WriteLine($"[{strings.Index}] {strings.GetString()}");
}
Constructors
BiffSstReader(scoped ref BiffReader)
Initializes a new instance of the BiffSstReader struct over the SST record the parent
reader is positioned on.
public BiffSstReader(scoped ref BiffReader reader)
Parameters
readerBiffReaderThe parent reader, positioned on an
SSTrecord.
Exceptions
- InvalidOperationException
Thrown when
readeris not positioned on anSSTrecord.- BiffFormatException
Thrown when the record is too short to hold the table header.
Properties
Current
Gets the span-backed view of the current string.
public readonly BiffString Current { get; }
Property Value
- BiffString
The view over the string's characters and trailers within their record.
Exceptions
- InvalidOperationException
Thrown when no string is current, or the current string is fragmented.
HasCurrent
Gets a value indicating whether a string is current.
public readonly bool HasCurrent { get; }
Property Value
- bool
true after a successful Read(scoped ref BiffReader) until the table is exhausted.
HasExtendedData
Gets a value indicating whether the current string carries extended (phonetic) data.
public readonly bool HasExtendedData { get; }
Property Value
Exceptions
- InvalidOperationException
Thrown when no string is current.
HasRichRuns
Gets a value indicating whether the current string carries rich-text formatting runs.
public readonly bool HasRichRuns { get; }
Property Value
Exceptions
- InvalidOperationException
Thrown when no string is current.
Header
Gets the counts from the table header.
public readonly BiffSstHeader Header { get; }
Property Value
- BiffSstHeader
The total reference count and the unique string count.
Index
Gets the zero-based index of the current string within the table.
public readonly int Index { get; }
Property Value
- int
The index, or −1 before the first string has been read.
IsFragmented
Gets a value indicating whether the current string's characters straddled a continuation boundary and therefore have no contiguous view.
public readonly bool IsFragmented { get; }
Property Value
- bool
true when Current is unavailable and GetString() must be used.
Exceptions
- InvalidOperationException
Thrown when no string is current.
Length
Gets the declared character count of the current string.
public readonly int Length { get; }
Property Value
- int
The UTF-16 code-unit count.
Exceptions
- InvalidOperationException
Thrown when no string is current.
Methods
CopyTo(Span<char>)
Decodes the current string into the supplied destination, whether or not it is fragmented.
public readonly int CopyTo(Span<char> destination)
Parameters
Returns
- int
The number of characters written.
Exceptions
- InvalidOperationException
Thrown when no string is current.
- ArgumentException
Thrown when
destinationis shorter than Length.
GetString()
Decodes the current string into a new string, whether or not it is fragmented.
public readonly string GetString()
Returns
- string
The decoded text.
Exceptions
- InvalidOperationException
Thrown when no string is current.
Read(scoped ref BiffReader)
Advances to the next string in the table, consuming continuation records from the parent reader as needed.
public bool Read(scoped ref BiffReader reader)
Parameters
readerBiffReaderThe parent reader the table was created from.
Returns
- bool
true when a string was read; false once every declared string has been read, or once the table's records end at a string boundary before then.
Remarks
A string's characters may continue across several CONTINUE records, each opening with a flags byte that
selects the width of the characters it holds. A continuation record that holds only that flags byte contributes
no characters, and the string goes on in the next one.
The table ends where its records end: when the cursor reaches the end of the SST record or of its last
CONTINUE record between two strings, and the parent's next record is not a CONTINUE, the method
returns false and leaves the parent on the table's last record, even when fewer strings than
UniqueCount have been read.
Exceptions
- BiffFormatException
Thrown when a string header or its characters are truncated, including by the end of the table's records, or a continuation record is empty (holds no bytes, not even a flags byte) where character data was expected.
Applies to
| Product | Versions |
|---|---|
| .NET | 8, 10 |