Skip to main content

SaveStringToFileUTF16

Procedure SaveStringToFileUTF16( const aContents, aFileName : string)

Example​

procedure ScriptEvent(var Value: variant);
begin
  SaveStringToFileUTF16('Fictional payload',
    'C:\Fictional\Outbound\message-utf16le.txt');
end;

Usage​

SaveStringToFileUTF16 creates or replaces a file with BOM-free little-endian UTF-16 text.

Parameters

NameTypeDescription
aContentsstring, constVelox UTF-16 text/code units to write.
aFileNamestring, constDestination file path.

Returns

This procedure has no return value. Normal return is not a byte-count verification.

Behaviour

  • Output length is normally twice Length(aContents).
  • No BOM, terminator, length prefix or line-ending conversion is added.
  • Empty text creates/truncates a zero-byte file.

Errors

Open, allocation and encoding exceptions propagate. Velox write failure can be silent because the returned count is ignored. Verify critical output independently.

Usage notes

Use only when the receiving contract explicitly says BOM-free UTF-16LE. UTF-8 is usually more interoperable for new text formats.

Additional Technical Info​

SaveStringToFileUTF16 creates or replaces a file with the Delphi string's UTF-16 code units in little-endian byte order. It does not emit the FF FE BOM, validate surrogate structure or verify the terminal write count.

The example targets fictional content/path and would replace that destination. It is source-reviewed and was not executed by the documentation workflow.

Implementation

The direct registration calls the shared native overload with TEncoding.Unicode. The destination is created/truncated exclusively, then installed TUnicodeEncoding.GetBytes copies each 16-bit Delphi Char into two little-endian bytes. StringToFileStream calls Write once and ignores its result; the file closes in a finally block.

Edge cases and quirks

  • A consumer that requires a UTF-16 BOM may not recognise this BOM-free file automatically.
  • The encoder copies code units without validating surrogate pairing. Unpaired surrogates are preserved as raw UTF-16 units rather than rejected.
  • Destination creation/truncation precedes encoding and is non-atomic with no rollback.
  • The helper ignores the count from TStream.Write. A zero/short operating-system write can therefore return normally with partial output.
  • Parent directories, allowed roots, file size, round-trip decoding and final storage durability are not checked.
  • An existing Windows symbolic-link path is followed and its target truncated; the link object itself is not opened.

Side effects

Creates or irreversibly replaces the destination file.

Performance and concurrency

The complete two-byte-per-code-unit array coexists with the source string. The exclusive file handle prevents concurrent opens only during the direct synchronous write; publication is not atomic.

Related entries

External references

Created 2026-07-15