Skip to main content

LoadFileToStringUTF16

Function LoadFileToStringUTF16( const aFileName : string) : string

Example​

procedure ScriptEvent(var Value: variant);
begin
  Value := LoadFileToStringUTF16('C:\Fictional\Inbound\message-utf16le.txt');
end;

Usage​

LoadFileToStringUTF16 reads an entire file as little-endian UTF-16 text without BOM detection.

Parameters

NameTypeDescription
aFileNamestring, constPath of a file whose byte contract is UTF-16 little-endian.

Returns

The decoded Velox UTF-16 string. A stable empty file returns an empty string.

Errors

Path, open, seek, allocation and read failures propagate. Odd byte length and malformed surrogate structure do not themselves raise in the current decoder.

Usage notes

Use this entry only for an explicitly little-endian UTF-16 contract. Use LoadFileToString when a supported BOM should select the encoding and be consumed.

Additional Technical Info​

LoadFileToStringUTF16 reads the complete file as little-endian UTF-16 code units. It selects the byte order explicitly and does not inspect or remove a byte-order mark.

The example reads a fictional UTF-16LE file. It is source-reviewed and was not executed by the documentation workflow.

Implementation

The registered function calls vxFiles.LoadFileToString(aFileName, TEncoding.Unicode). That overload opens a read-only, share-deny-none TFileStream and passes it to vxStream.FileStreamToString. The helper reads the captured file bytes and calls installed TUnicodeEncoding.GetString. The decoder calculates ByteCount div 2 characters and copies little-endian 16-bit code units into the result.

Edge cases and quirks

  • A leading FF FE UTF-16LE BOM becomes U+FEFF in the returned string because explicit decoding does not skip a preamble.
  • An odd final byte is silently ignored by the installed ByteCount div 2 implementation.
  • UTF-16 code units are copied without validating surrogate pairing. Unpaired surrogates can remain in the Delphi string.
  • Big-endian input is byte-swapped into different characters rather than detected or rejected.
  • File size is narrowed to signed LongInt; the helper ignores a short read and fmShareDenyNone permits a writer to mutate the file during decoding.

Side effects

Opens and reads the file without deliberately modifying it.

Performance and concurrency

The complete byte buffer and UTF-16 result coexist in memory. The call is synchronous and non-atomic with respect to permitted external writers.

Related entries

External references

Created 2026-07-15