RAM & File Streams (HStreams unit)
- ThStream
- Clear
- Read
- Write
- Read_Byte
- Write_Byte
- Read_Word
- Write_Word
- Read_Double
- Write_Double
- Read_Extended
- Write_Extended
- Init_UCS2_Stream
- Check_Stream_Is_UCS2
- Init_UTF8_Stream
- Check_Stream_Is_UTF8
- Check_Stream_Is_Windows_Portable_Executable
- Check_Stream_Is_Zlib_Compressed
- Read_WideText
- Write_WideText
- Read_AnsiText
- Write_AnsiText
- Write_AnsiLine
- CopyFrom (ThStream)
- CopyFrom (TStream)
- Pos_AnsiStr
- Pos_WideStr
- Calc_CRC_Word
- Delete
- Adapter
- Properties
- ThDelphiStreamAdapter
- ThFileStream
- ThMemoryStream
- Assign_And_Protect_Memory_Block
- Reduce_Spare_Allocation
- Read
- Write
- Load_From_File
- Save_To_File
- CopyFrom_MS
- Read_WideText
- Write_WideText
- Read_AnsiText
- Write_AnsiText
- Replace_AnsiString
- Read_From_Socket
- Write_8KB_Packet_To_Socket
- Write_Everything_To_Socket
- Encode_SYE_Sapphire
- Decode_SYE_Sapphire
- Encode_OLD_Sapphire (Win32)
- Decode_OLD_Sapphire (Win32)
- Compress
- DeCompress
- Properties
- Utility Functions
ThStream
Abstract base stream that defines unified typed I/O, text operations, search, copy, checksums, and format detection.All concrete stream classes inherit from it.
Clear
Resets stream size to zero and clears last I/O error state.procedure ThStream.Clear;Read
Base virtual reader (overridden by file/memory implementations).function ThStream.Read(var Buffer; Count: Cardinal): Cardinal; virtual;Parameters
- Buffer: untyped memory buffer.
- Count: Cardinal.
Return Value
Returns Cardinal.Write
Base virtual writer (overridden by file/memory implementations).function ThStream.Write(const Buffer; Count: Cardinal): Cardinal; virtual;Parameters
- Buffer: untyped memory buffer.
- Count: Cardinal.
Return Value
Returns Cardinal.Read_Byte
Reads 1 byte and sets error state if insufficient data is available.function ThStream.Read_Byte: Byte;Return Value
Returns Byte.Write_Byte
Writes one byte and returns success status.function ThStream.Write_Byte(const Value: Byte): Boolean;Parameters
- Value: Byte.
Return Value
Returns Boolean.Read_Word
Reads 2 bytes as Word with safety/error tracking.function ThStream.Read_Word: Word;Return Value
Returns Word.Write_Word
Writes 2 bytes as Word.function ThStream.Write_Word(const Value: Word): Boolean;Parameters
- Value: Word.
Return Value
Returns Boolean.Read_Double
Reads 8 bytes as Double.function ThStream.Read_Double: Double;Return Value
Returns Double.Write_Double
Writes 8 bytes as Double.function ThStream.Write_Double(Value: Double): Boolean;Parameters
- Value: Double.
Return Value
Returns Boolean.Read_Extended (Win32)
Reads Delphi Extended (10 bytes) on Win32 builds.function ThStream.Read_Extended: Extended;Return Value
Returns Extended.Write_Extended (Win32)
Writes Delphi Extended (10 bytes) on Win32 builds.function ThStream.Write_Extended(Value: Extended): Boolean;Parameters
- Value: Extended.
Return Value
Returns Boolean.Init_UCS2_Stream
Writes UCS2 BOM (`FF FE`) at stream start.procedure ThStream.Init_UCS2_Stream;Check_Stream_Is_UCS2
Checks for UCS2 BOM at beginning.function ThStream.Check_Stream_Is_UCS2: Boolean;Return Value
Returns Boolean.Init_UTF8_Stream
Writes UTF-8 BOM (`EF BB BF`) at stream start.procedure ThStream.Init_UTF8_Stream;Check_Stream_Is_UTF8
Checks for UTF-8 BOM at beginning.function ThStream.Check_Stream_Is_UTF8: Boolean;Return Value
Returns Boolean.Check_Stream_Is_Windows_Portable_Executable
Quick PE signature probe (`MZ` header pattern).function ThStream.Check_Stream_Is_Windows_Portable_Executable: Boolean;Return Value
Returns Boolean.Check_Stream_Is_Zlib_Compressed
Checks expected zlib framing markers used by this implementation.function ThStream.Check_Stream_Is_Zlib_Compressed: Boolean;Return Value
Returns Boolean.Read_WideText
Reads UTF-16/UCS2 characters with safe bounds logic and null-stop behavior.function ThStream.Read_WideText(ReadLength: Cardinal): String; virtual;Parameters
- ReadLength: Cardinal.
Return Value
Returns String.Write_WideText
Writes UTF-16 text, with optional fixed-length padding.function ThStream.Write_WideText(const Value: String; WriteLength: Cardinal = 0; Fill: Byte = 0): Boolean; virtual;Parameters
- Value: String.
- WriteLength: Cardinal = 0.
- Fill: Byte = 0.
Return Value
Returns Boolean.Read_AnsiText
Reads ANSI bytes into a RawByteString.function ThStream.Read_AnsiText(ReadLength: Cardinal): RawByteString; virtual;Parameters
- ReadLength: Cardinal.
Return Value
Returns RawByteString.Write_AnsiText
Writes ANSI text with optional fixed-length fill.function ThStream.Write_AnsiText(const Value: RawByteString; WriteLength: Cardinal = 0; Fill: Byte = 0): Boolean; virtual;Parameters
- Value: RawByteString.
- WriteLength: Cardinal = 0.
- Fill: Byte = 0.
Return Value
Returns Boolean.Write_AnsiLine
Writes an ANSI line plus CRLF.function ThStream.Write_AnsiLine(const Text: RawByteString): Boolean;Parameters
- Text: RawByteString.
Return Value
Returns Boolean.CopyFrom (ThStream source)
Copies bytes from another ThStream; supports optional slow-copy mode.function ThStream.CopyFrom(Source: ThStream; Count: Int64; SlowerCopy: Boolean = False): Int64;Parameters
- Source: ThStream.
- Count: Int64.
- SlowerCopy: Boolean = False.
Return Value
Returns Int64.CopyFrom (TStream source)
Copies bytes from standard Delphi TStream.function ThStream.CopyFrom(Source: TStream; Count: Int64): Int64;Parameters
- Source: TStream.
- Count: Int64.
Return Value
Returns Int64.Pos_AnsiStr
Searches ANSI pattern inside stream range; supports case sensitivity mode.function ThStream.Pos_AnsiStr(FindString: RawByteString; FromPos: Int64; ToPos: Int64 = 0; CaseSensitive: Boolean = False): Int64;Parameters
- FindString: RawByteString.
- FromPos: Int64.
- ToPos: Int64 = 0.
- CaseSensitive: Boolean = False.
Return Value
Returns Int64.Pos_WideStr
Searches UTF-16/wide pattern inside stream range; supports case sensitivity mode.function ThStream.Pos_WideStr(FindString: String; FromPos: Int64; ToPos: Int64 = 0; CaseSensitive: Boolean = False): Int64;Parameters
- FindString: String.
- FromPos: Int64.
- ToPos: Int64 = 0.
- CaseSensitive: Boolean = False.
Return Value
Returns Int64.Calc_CRC_Word
Calculates CRC word of whole stream or selected sub-range.function ThStream.Calc_CRC_Word(ExFromPos: Int64 = -1; ExUntilPos: Int64 = -1): Word;Parameters
- ExFromPos: Int64 = -1.
- ExUntilPos: Int64 = -1.
Return Value
Returns Word.Delete
Deletes a byte range from the stream and compacts the remaining data.function ThStream.Delete(FromPos, Count: Int64): Boolean;Parameters
- FromPos, Count: Int64.
Return Value
Returns Boolean.Adapter
Returns a lazily-created ThDelphiStreamAdapter wrapper for VCL/FMX APIs expecting TStream.function ThStream.Adapter: ThDelphiStreamAdapter;Return Value
Returns ThDelphiStreamAdapter.Properties
Core runtime properties for every stream instance.
property ThStream.Position: Int64 read GetPosition write SetPosition;
property ThStream.Size: Int64 read GetSize write SetSize;
property ThStream.Error_On_Last_IO: Boolean read _Last_IO_Error;
Property Details
- ThStream.Position: abstract cursor property in base class. Real behavior comes from descendants.
- ThStream.Size: abstract size property in base class. Real behavior comes from descendants.
- ThStream.Error_On_Last_IO: read-only status flag of last low-level I/O operation.
Setter Logic In Descendants
- ThFileStream.SetPosition: clamps to EOF when value is above file size.
- ThFileStream.SetSize: truncates/extends file using OS API and keeps cursor inside bounds.
- ThMemoryStream.SetPosition: clamps to range 0..Size.
- ThMemoryStream.SetSize: blocked on protected streams; reallocates by capacity tiers and resets stream on allocation failure.
ThDelphiStreamAdapter
Bridge class that adapts ThStream to native Delphi TStream contract.Read
TStream-compatible read implementation that delegates to owner stream.function ThDelphiStreamAdapter.Read(var Buffer; Count: Integer): Integer; override;Parameters
- Buffer: untyped memory buffer.
- Count: Integer.
Return Value
Returns Integer.Write
TStream-compatible write implementation that delegates to owner stream.function ThDelphiStreamAdapter.Write(const Buffer; Count: Integer): Integer; override;Parameters
- Buffer: untyped memory buffer.
- Count: Integer.
Return Value
Returns Integer.Seek (Integer overload)
Legacy seek overload for old Delphi stream APIs.function ThDelphiStreamAdapter.Seek(Offset: Integer; Origin: Word): Integer; override;Parameters
- Offset: Integer.
- Origin: Word.
Return Value
Returns Integer.Seek (Int64 overload)
Modern seek overload using TSeekOrigin.function ThDelphiStreamAdapter.Seek(const Offset: Int64; Origin: TSeekOrigin): Int64; override;Parameters
- Offset: Int64.
- Origin: TSeekOrigin.
Return Value
Returns Int64.GetSize / SetSize
Size accessors forwarded to owner stream in both Integer and Int64 signatures.
function ThDelphiStreamAdapter.GetSize: Int64; override;
procedure ThDelphiStreamAdapter.SetSize(NewSize: Integer); override;
procedure ThDelphiStreamAdapter.SetSize(const NewSize: Int64); override;
Parameters
- NewSize: target size for SetSize overloads.
Return Value
`ThDelphiStreamAdapter.GetSize` returns current owner size.Both `SetSize` overloads have no return value and delegate to owner stream.
ThFileStream
File-backed stream implementation on top of Windows file handles.OpenFileStream
Factory helper that creates and opens a ThFileStream in one call. DO NOT USE ThFileStream.Create directly!Use it when you want safe open logic plus explicit access mode handling.
TYPE
ThFileStream_Access = (he_ReadFile, he_UpdateFile, he_CreateNewFile, he_ReadFile_AnyState);
function OpenFileStream(FileName: String; Access: ThFileStream_Access; var FS: ThFileStream; Rename_Max_Size: Int64 = 0): Boolean;
Parameters
- FileName: String.
- Access: ThFileStream_Access.
he_ReadFile: opens existing file as read-only (GENERIC_READ,FILE_SHARE_READ).
he_UpdateFile: opens existing file for read/write with exclusive lock (no sharing). If file does not exist, automatically switches to he_CreateNewFile.
he_CreateNewFile: deletes existing file (if any) and creates a new empty file for read/write (CREATE_ALWAYS, no sharing).
he_ReadFile_AnyState: opens existing file as read-only but allows both readers and writers in parallel (FILE_SHARE_READ OR FILE_SHARE_WRITE). - FS: ThFileStream.
- Rename_Max_Size: Int64 = 0.
Return Value
Returns Boolean.Goto_EOF
Moves current position to end-of-file for append scenarios.procedure ThFileStream.Goto_EOF;Read
Reads bytes from file handle at current stream position.function ThFileStream.Read(var Buffer; Count: Cardinal): Cardinal; override;Parameters
- Buffer: untyped memory buffer.
- Count: Cardinal.
Return Value
Returns Cardinal.Write
Writes bytes to file handle at current stream position.function ThFileStream.Write(const Buffer; Count: Cardinal): Cardinal; override;Parameters
- Buffer: untyped memory buffer.
- Count: Cardinal.
Return Value
Returns Cardinal.ThMemoryStream
In-RAM stream with custom allocator, direct buffer access, network helpers, compression, and encryption support.Assign_And_Protect_Memory_Block
Assigns external block from another memory stream as protected (read-style usage, no reallocation semantics).function ThMemoryStream.Assign_And_Protect_Memory_Block(SourceMS: ThMemoryStream; FromPosition, BlockSize: NativeUInt): Boolean;Parameters
- SourceMS: ThMemoryStream.
- FromPosition, BlockSize: NativeUInt.
Return Value
Returns Boolean.Reduce_Spare_Allocation
Trims unused reserved capacity to reduce memory footprint.procedure ThMemoryStream.Reduce_Spare_Allocation;Read
Reads bytes from internal memory pointer and advances cursor.function ThMemoryStream.Read(var Buffer; Count: Cardinal): Cardinal; override;Parameters
- Buffer: untyped memory buffer.
- Count: Cardinal.
Return Value
Returns Cardinal.Write
Writes bytes to internal memory pointer; auto-grows capacity when needed.function ThMemoryStream.Write(const Buffer; Count: Cardinal): Cardinal; override;Parameters
- Buffer: untyped memory buffer.
- Count: Cardinal.
Return Value
Returns Cardinal.Load_From_File
Loads file content into memory stream; can optionally attempt locked-file access and tail-copy mode.function ThMemoryStream.Load_From_File(FileName: String; Access_Locked_File: Boolean = False; CopyFromEnd: Int64 = 0): Boolean;Parameters
- FileName: String.
- Access_Locked_File: Boolean = False.
- CopyFromEnd: Int64 = 0.
Return Value
Returns Boolean.Save_To_File
Saves current buffer to file and optionally clears stream after successful save.function ThMemoryStream.Save_To_File(FileName: String; Reset_After_Save: Boolean = False): Boolean;Parameters
- FileName: String.
- Reset_After_Save: Boolean = False.
Return Value
Returns Boolean.CopyFrom_MS
Efficient copy helper from another ThMemoryStream.function ThMemoryStream.CopyFrom_MS(Source: ThMemoryStream; Count: Int64): Int64;Parameters
- Source: ThMemoryStream.
- Count: Int64.
Return Value
Returns Int64.Read_WideText
Memory-stream override for wide text reading.function ThMemoryStream.Read_WideText(ReadLength: Cardinal): String; override;Parameters
- ReadLength: Cardinal.
Return Value
Returns String.Write_WideText
Memory-stream override for wide text writing.function ThMemoryStream.Write_WideText(const Value: String; WriteLength: Cardinal = 0; Fill: Byte = 0): Boolean; override;Parameters
- Value: String.
- WriteLength: Cardinal = 0.
- Fill: Byte = 0.
Return Value
Returns Boolean.Read_AnsiText
Memory-stream override for ANSI text reading.function ThMemoryStream.Read_AnsiText(ReadLength: Cardinal): RawByteString; override;Parameters
- ReadLength: Cardinal.
Return Value
Returns RawByteString.Write_AnsiText
Memory-stream override for ANSI text writing.function ThMemoryStream.Write_AnsiText(const Value: RawByteString; WriteLength: Cardinal = 0; Fill: Byte = 0): Boolean; override;Parameters
- Value: RawByteString.
- WriteLength: Cardinal = 0.
- Fill: Byte = 0.
Return Value
Returns Boolean.Replace_AnsiString
In-place byte-range search/replace for ANSI content inside the stream.function ThMemoryStream.Replace_AnsiString(FindString, Replaceto: RawByteString; FromPos: Int64 = 0; ToPos: Int64 = 0; CaseSensitive: Boolean = False): Boolean;Parameters
- FindString, Replaceto: RawByteString.
- FromPos: Int64 = 0.
- ToPos: Int64 = 0.
- CaseSensitive: Boolean = False.
Return Value
Returns Boolean.Read_From_Socket
Reads network data from socket directly into stream buffer with timeout control.function ThMemoryStream.Read_From_Socket(var _Socket: NativeUInt; const TimeOut: Double; Read_Bytes_Limitation: Word = 0): Boolean;Parameters
- _Socket: NativeUInt.
- TimeOut: Double.
- Read_Bytes_Limitation: Word = 0.
Return Value
Returns Boolean.Write_8KB_Packet_To_Socket
Sends one packet chunk (up to 8KB) from stream buffer to socket.function ThMemoryStream.Write_8KB_Packet_To_Socket(var _Socket: NativeUInt): Boolean;Parameters
- _Socket: NativeUInt.
Return Value
Returns Boolean.Write_Everything_To_Socket
Attempts to transmit entire stream payload to socket.function ThMemoryStream.Write_Everything_To_Socket(var _Socket: NativeUInt; Clear_Buffer_IF_Sent: Boolean = False): Boolean;Parameters
- _Socket: NativeUInt.
- Clear_Buffer_IF_Sent: Boolean = False.
Return Value
Returns Boolean.Encode_SYE_Sapphire
Encrypts stream content with SYE Sapphire using a byte-array private key.function ThMemoryStream.Encode_SYE_Sapphire(const Private_Key: array of Byte): Boolean;Parameters
- Private_Key: array of Byte.
Return Value
Returns Boolean.Decode_SYE_Sapphire
Decrypts SYE Sapphire content using the same private key material.function ThMemoryStream.Decode_SYE_Sapphire(const Private_Key: array of Byte): Boolean;Parameters
- Private_Key: array of Byte.
Return Value
Returns Boolean.Encode_OLD_Sapphire (Win32)
Legacy Sapphire encoder (string-key variant), available on Win32 only.function ThMemoryStream.Encode_OLD_Sapphire(const Sapphire_Key: String): Boolean;Parameters
- Sapphire_Key: String.
Return Value
Returns Boolean.Decode_OLD_Sapphire (Win32)
Legacy Sapphire decoder (string-key variant), available on Win32 only.function ThMemoryStream.Decode_OLD_Sapphire(const Sapphire_Key: String): Boolean;Parameters
- Sapphire_Key: String.
Return Value
Returns Boolean.Compress
Compresses current buffer via zlib format used by the unit (limited to 4GB data range).function ThMemoryStream.Compress(Level: Byte = 4): Boolean;Parameters
- Level: Byte = 4.
Return Value
Returns Boolean.DeCompress
Decompresses zlib data produced/expected by this unit (limited to 4GB data range).function ThMemoryStream.DeCompress: Boolean;Return Value
Returns Boolean.Properties
Memory-stream specific exposed internals and allocation diagnostics.
property ThMemoryStream.Memory: Pointer read _Memory_Ptr;
property ThMemoryStream.Last_Allocation_Had_Errors: Boolean read _Last_Allocation_Had_Errors;
Property Details
- ThMemoryStream.Memory: pointer to current internal buffer; may change after writes/realloc/compress/decompress.
- ThMemoryStream.Last_Allocation_Had_Errors: indicates latest allocation/reallocation failure or protected-block restriction hit.
Related Restrictions
- Assign_And_Protect_Memory_Block sets protected mode; resizing and many mutating operations are blocked.
- SetSize uses growth tiers (512KB, 1MB, 8MB, 20MB, then 40MB steps) and includes Win32 safety limit around 1.8GB.
Create_Package_File
Builds a package (ZIP container) from a list of source files.function Create_Package_File(ZipFileName, Source_Files_List: String): Boolean;Parameters
- ZipFileName, Source_Files_List: String.
Return Value
Returns Boolean.Get_Files_List
Returns the internal file list of a package file.function Get_Files_List(ZipFileName: String): String;Parameters
- ZipFileName: String.
Return Value
Returns String.Extract_File_Into_MS
Extracts one file from a package directly into memory (no temporary disk file).function Extract_File_Into_MS(FileName, ZipFileName: String; MS: ThMemoryStream): Boolean;Parameters
- FileName, ZipFileName: String.
- MS: ThMemoryStream.
Return Value
Returns Boolean.Extract_All_Files
Extracts an entire package to a target folder structure.function Extract_All_Files(ZipFileName, ExtractTo: String): Boolean;Parameters
- ZipFileName, ExtractTo: String.
Return Value
Returns Boolean.Fast_File_CRC_Word
Computes a quick CRC word checksum for a file, mainly for integrity checks.function Fast_File_CRC_Word(FileName: String): Word;Parameters
- FileName: String.
Return Value
Returns Word.Decode_Quoted_Printable
Decodes quoted-printable text range from a source memory stream into a target stream.function Decode_Quoted_Printable(Source: ThMemoryStream; FromPos, UntilPos: Cardinal; var Target: ThMemoryStream): Boolean;Parameters
- Source: ThMemoryStream.
- FromPos, UntilPos: Cardinal.
- Target: ThMemoryStream.
Return Value
Returns Boolean.Write_Log_File_From_Stream
Persists stream content to the log file pipeline (with optional extra CRLF handling).procedure Write_Log_File_From_Stream(Source: ThStream; ExtCRLF: Boolean = False);Parameters
- Source: ThStream.
- ExtCRLF: Boolean = False.
Encode_BASE64_String
Encodes binary text payload to BASE64.function Encode_BASE64_String(Input: RawByteString): RawByteString;Parameters
- Input: RawByteString.
Return Value
Returns RawByteString.Decode_BASE64_String
Decodes BASE64 back to binary payload.function Decode_BASE64_String(Input: RawByteString): RawByteString;Parameters
- Input: RawByteString.
Return Value
Returns RawByteString.Encode_BASE64
Stream-to-stream BASE64 encoder.procedure Encode_BASE64(Input, Output: ThMemoryStream);Parameters
- Input, Output: ThMemoryStream.
Decode_BASE64
Range-based stream BASE64 decoder.procedure Decode_BASE64(Source, Target: ThMemoryStream; FromPos, UntilPos: NativeUInt);Parameters
- Source, Target: ThMemoryStream.
- FromPos, UntilPos: NativeUInt.
Generate_Sapphire_Key_Array_For_Delphi
Generates Delphi-ready byte-array literal text for Sapphire keys.function Generate_Sapphire_Key_Array_For_Delphi(KeyLen: Integer): String;Parameters
- KeyLen: Integer.
Return Value
Returns String.Test_Does_String_Contain_Only_BASE64_Chars
Validation helper to ensure a string contains only legal BASE64 characters.function Test_Does_String_Contain_Only_BASE64_Chars(const Input: String): Boolean;Parameters
- Input: String.