TBytes

TBytes = array of Byte

Example

procedure BuildHeader(var Data: TBytes);
begin
  SetLength(Data, 4);
  Data[0] := $56; // V
  Data[1] := $58; // X
  Data[2] := 1;   // version
  Data[3] := 0;   // flags
end;

Usage

TBytes stores a zero-based managed sequence of raw 8-bit values for binary Velox data boundaries.

Allocation and indexing

• SetLength(Data, N) allocates N byte elements. New elements are initialized to zero.
• Length(Data) returns the byte count, not a character count or encoded-text length.
• For a nonempty buffer, valid indexes are 0 .. High(Data). An empty buffer has High(Data) = -1.
• Shrinking preserves the first N bytes. Growing preserves existing bytes and adds zero-valued bytes.
• A negative requested length is silently clamped to zero by the current Velox scripting runtime. Pass zero explicitly when clearing.
• Out-of-range reads or writes raise a Velox scripting range error; validate external offsets and lengths before indexing.

Binary and text boundaries

TBytes has no character encoding. The bytes $56,$58 happen to be ASCII/UTF-8 for VX, but arbitrary buffers may contain zero bytes or invalid text sequences. Choose the conversion by contract:

• Use Base64EncodeBytes and Base64DecodeBytes for text-only interchange.
• Use LoadFileToBytes and SaveBytesToFile for whole-file binary transfer, after applying path and size controls.
• Use BytesToStream and StreamToBytes when an API requires a memory stream.
• Compression helpers return or consume compressed bytes; compressed output must not be interpreted as text.

The RawContent surface of an API request also uses TBytes. Treat it as the exact payload and obtain content type/encoding from the protocol rather than guessing from the bytes.

Aliasing, lifetime and limits

After assigning one TBytes variable to another, changing an element through either variable can change the value seen through the other. Resizing can separate them, but a same-length SetLength does not create a copy. When an independent buffer is required, allocate a separate destination and copy the elements.

Memory use is proportional to the requested byte count, and several helper functions read complete payloads into memory. Validate file sizes, decoded Base64 sizes and decompression limits before allocating. Velox releases the array automatically after it is no longer used.

Additional Technical Info

TBytes is the script-visible dynamic byte-buffer type registered by the modified PascalScript compiler. Each element is an unsigned Byte in the range 0..255. Array positions are zero-based.

Related Code Library entries

• Byte - element range and conversion rules.
• Arrays - shared dynamic-array behavior and interchange guidance.

External references

• Embarcadero System.TBytes - Delphi byte-array alias.
• Embarcadero structured types - dynamic-array indexing, sharing and lifetime.
• Free Pascal dynamic arrays - compatible zero-based array model.

Created 2026-07-15