Skip to main content

StreamToStringUTF8

function StreamToStringUTF8(M : TStream) : string

Example​

procedure ScriptEvent(var Value: variant);
var
  Buffer: TMemoryStream;
begin
  Buffer := TMemoryStream.Create;
  try
    StringToStreamUTF8('Fictional order 1001', Buffer);
    Value := StreamToStringUTF8(Buffer);
  finally
    Buffer.Free;
  end;
end;

Usage​

StreamToStringUTF8 reads an entire stream from the beginning and decodes it explicitly as UTF-8.

Parameters

NameTypeDescription
MTStreamExisting readable, seekable caller-owned stream. The current position is ignored.

Returns

The decoded Velox Unicode string. Empty input returns an empty string.

Errors

Nil-object, seek, read, allocation and EEncodingError failures propagate. No partial string or previous position is restored.

Usage notes

For a UTF-8 contract that permits an optional BOM and wants it consumed, use StreamToString only if its ANSI fallback is also acceptable; otherwise remove the BOM in controlled byte-processing code.

Additional Technical Info​

StreamToStringUTF8 decodes the complete stream as UTF-8 regardless of its contents. Use it for BOM-free UTF-8 and for contracts where a leading BOM should remain visible to the caller.

The example round-trips fictional text in memory. It is source-reviewed and is not executed by the documentation workflow.

Implementation

The wrapper calls MemoryStreamToString(M, TEncoding.UTF8). The shared helper rewinds and reads the complete stream, then installed TUTF8Encoding.GetString converts the array using Windows code page UTF-8 with MB_ERR_INVALID_CHARS enabled.

Edge cases and quirks

  • A leading UTF-8 BOM (EF BB BF) is decoded as U+FEFF; it is not stripped by this explicit path.
  • Malformed, overlong, truncated or otherwise invalid UTF-8 is rejected by the current decoder rather than silently treated as ANSI.
  • Embedded U+0000 is preserved inside the managed string.
  • The helper ignores a short Read result, changes stream position and safely supports only signed-LongInt byte counts.
  • The function performs no Unicode normalisation; canonically equivalent strings can remain byte-distinct before decoding and code-point-distinct after it.

Side effects

Changes M.Position; does not change stream content or ownership.

Performance and concurrency

Linear time and memory; input bytes and output string coexist. External synchronisation is required for shared streams.

Related entries

External references

Created 2026-07-15