Skip to main content

LoadFileToString

Function LoadFileToString( const aFileName : string) : string;

Example​

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

Usage​

LoadFileToString reads an entire file as text using BOM detection with ASCII fallback.

Parameters

NameTypeDescription
aFileNamestring, constPath of the text file. Relative paths are resolved against the Velox process current directory.

Returns

The decoded Velox string. A stable empty file returns an empty string.

Behaviour

  • BOM detection tries UTF-8, UTF-16LE and UTF-16BE preambles; it is not statistical encoding detection.
  • BOM-free bytes are decoded as ASCII. BOM-free UTF-8 is safe only while every byte is in the ASCII range.
  • UTF-32 and other encodings are not detected.
  • The complete file is decoded as one string; line endings and embedded U+0000 characters are not removed.

Errors

File-open, seek, allocation, read and encoding failures propagate. A recognised malformed UTF-8 payload can raise EEncodingError. No partial string is returned.

Usage notes

Use this routine only when the input contract permits BOM selection and ASCII fallback. Prefer an explicit encoding-specific loader for deterministic integration formats.

Additional Technical Info​

LoadFileToString reads the complete file, recognises a leading UTF-8, UTF-16LE or UTF-16BE byte-order mark (BOM), removes that preamble and decodes the remaining bytes. When none of those BOMs is present, the current implementation uses Delphi's seven-bit ASCII encoding—not ANSI and not UTF-8.

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

Implementation

The script runtime deliberately registers adapter LoadFileToString_P to select the public one-argument overload. That overload calls vxFiles.LoadFileToString(aFileName, nil), which opens a TFileStream using fmOpenRead or fmShareDenyNone and delegates to vxStream.FileStreamToString.

The helper rewinds the stream, narrows Size to LongInt, allocates and reads one byte array, then calls installed Studio 37.0 TEncoding.GetBufferEncoding with TEncoding.ASCII as its explicit fallback. It passes the returned BOM length to GetString, so a recognised preamble is excluded from the result.

Edge cases and quirks

  • This fallback differs from StreamToString, whose related stream helper passes ANSI. The two similarly named entries can therefore decode the same BOM-free high bytes differently.
  • The fallback also differs from default SaveStringToFile, which writes with TEncoding.Default when no encoding is supplied. A non-ASCII default-encoded file is not a reliable round trip through this loader unless it includes a supported BOM or an explicit loader is used.
  • The helper stores file size in signed LongInt; files outside that range are unsupported and may fail during narrowing or allocation.
  • A single Read return count is ignored. Concurrent truncation can leave zero-filled bytes in the decode buffer, while growth beyond the captured size is ignored.
  • fmShareDenyNone permits concurrent writing, so the returned text is not guaranteed to represent one atomic file version.

Side effects

Opens and reads the file. It does not deliberately modify it.

Performance and concurrency

The complete byte array and decoded string coexist in memory. Time and peak memory are linear in file size. Coordinate writers and impose an input-size limit where files are not already governed.

Related entries

External references

Created 2026-07-15