cToolsStream Class

Stream file operations class based on ADODB.Stream, supports text and binary data read/write.

Description

cToolsStream is a wrapper for ADODB.Stream object, providing simplified file read/write interface. Supports line-by-line read/write mode, suitable for processing text configuration files.

Required Library:

• Microsoft ActiveX Data Objects 2.8 Library (msado28.tlb)

Features:

• Supports text and binary modes
• Supports line-by-line read/write (splits file content by lines and stores)
• Automatically handles encoding (UTF-8, ANSI, etc.)

---

Properties

Property Name	Type	Description
Inst	ADODB.Stream	ADO Stream instance object
LastError	String	Last error message
LineNumber	Long	Current line number (used in line mode)
UseLine	Boolean	Whether line-by-line read/write mode is enabled
LineData	cCollection	Line-stored data collection
Txt	cToolsStr	String tools instance

---

Methods

UseLineMode

Sets whether to enable line-by-line read/write mode.

Syntax:

Public Function UseLineMode(v As Boolean) As cToolsStream

Parameters:

Parameter	Type	Description
v	Boolean	True=enable line mode, False=disable

Returns:

• Returns self instance, supports method chaining

Description:

• When enabled, LineData collection serves as the data body
• Inst saves the original file content

Example:

Dim Stream As New cToolsStream

' Enable line mode
Stream.UseLineMode True

---

ReadLine

Reads one line of content from specified line.

Syntax:

Public Function ReadLine(Optional ByVal Line As Long) As String

Parameters:

Parameter	Type	Description
Line	Long	Optional. Specify line number (1-based), if not provided uses LineNumber

Returns:

• Line content string

Exceptions:

• Throws error when line mode is not enabled

Description:

• After reading, LineNumber automatically increments by 1
• If Line parameter is provided, sets LineNumber = Line

Example:

Dim Stream As New cToolsStream
Stream.UseLineMode True

' Load file (will auto-split into lines)
Stream.LoadFileAsText "C:\\data\\config.ini", "UTF-8"

' Read line by line
Dim Line1 As String
Line1 = Stream.ReadLine()  ' Read line 1

Dim Line5 As String
Line5 = Stream.ReadLine(5)  ' Read line 5

---

WriteLine

Writes content to specified line.

Syntax:

Public Function WriteLine(Text As String, Optional ByVal Line As Long) As Boolean

Parameters:

Parameter	Type	Description
Text	String	Content to write
Line	Long	Optional. Specify line number, if not provided uses LineNumber

Returns:

• True - Write successful

Exceptions:

• Throws error when line mode is not enabled

Description:

• After writing, LineNumber automatically increments by 1
• If line number already exists, replaces original content

Example:

Dim Stream As New cToolsStream
Stream.UseLineMode True

' Write multiple lines
Stream.WriteLine "[Section1]", 1
Stream.WriteLine "Key1=Value1", 2
Stream.WriteLine "Key2=Value2", 3

' Save file
Stream.SaveFileAsText "C:\\data\\config.ini", , "UTF-8"

---

LoadFileAsText

Loads file in text mode.

Syntax:

Public Function LoadFileAsText(ByVal FileName As String, Optional ByVal CharSet As String = "UTF-8") As String

Parameters:

Parameter	Type	Description
FileName	String	File path
CharSet	String	Optional. Character encoding, default is UTF-8

Returns:

• File content string

Description:

• If line mode is enabled, content is auto-split by lines and stored in LineData
• LineNumber resets to 1 after loading

Example:

Dim Stream As New cToolsStream
Dim Content As String

' Basic loading
Content = Stream.LoadFileAsText("C:\\data\\readme.txt", "UTF-8")
Debug.Print Content

' Load in line mode
Stream.UseLineMode True
Content = Stream.LoadFileAsText("C:\\data\\config.ini", "UTF-8")
' Now you can use ReadLine to access each line
Debug.Print Stream.ReadLine(1)

---

SaveFileAsText

Saves file in text mode.

Syntax:

Public Function SaveFileAsText(ByVal FileName As String, Optional Data As Variant, Optional ByVal CharSet As String = "UTF-8") As Boolean

Parameters:

Parameter	Type	Description
FileName	String	Target file path
Data	Variant	Optional. Data to save, if not provided uses LineData (line mode) or Inst
CharSet	String	Optional. Character encoding, default is UTF-8

Returns:

• True - Save successful

Description:

• Overwrites if file already exists
• In line mode, if Data is not provided, automatically uses LineData collection

Example:

Dim Stream As New cToolsStream

' Save string directly
Stream.SaveFileAsText "C:\\data\\output.txt", "Hello World", "UTF-8"

' Save in line mode
Stream.UseLineMode True
Stream.WriteLine "Line 1", 1
Stream.WriteLine "Line 2", 2
Stream.SaveFileAsText "C:\\data\\lines.txt", , "UTF-8"

---

LoadFileAsBinary

Loads file in binary mode.

Syntax:

Public Function LoadFileAsBinary(ByVal Path As String, OutData() As Byte) As Boolean

Parameters:

Parameter	Type	Description
Path	String	File path
OutData	Byte()	Output byte array

Returns:

• True - Load successful
• False - Load failed (error message in LastError)

Example:

Dim Stream As New cToolsStream
Dim Bytes() As Byte

If Stream.LoadFileAsBinary("C:\\data\\file.bin", Bytes) Then
    Debug.Print "Load successful, byte count: " & UBound(Bytes) + 1
Else
    Debug.Print "Load failed: " & Stream.LastError
End If

---

SaveFileAsBinary

Saves file in binary mode.

Syntax:

Public Function SaveFileAsBinary(ByVal Path As String, OutData() As Byte) As Boolean

Parameters:

Parameter	Type	Description
Path	String	Target file path
OutData	Byte()	Byte array to save

Returns:

• True - Save successful
• False - Save failed (error message in LastError)

Example:

Dim Stream As New cToolsStream
Dim Bytes() As Byte

' Fill data
ReDim Bytes(0 To 3)
Bytes(0) = &H48  ' H
Bytes(1) = &H65  ' e
Bytes(2) = &H6C  ' l
Bytes(3) = &H6C  ' l

If Stream.SaveFileAsBinary("C:\\data\\output.bin", Bytes) Then
    Debug.Print "Save successful"
Else
    Debug.Print "Save failed: " & Stream.LastError
End If

---

Usage Examples

Example 1: Simple Text File Read/Write

Sub SimpleTextExample()
    Dim Stream As New cToolsStream
    Dim Content As String
    
    ' Write file
    Stream.SaveFileAsText "C:\\data\\test.txt", "Hello World 你好世界", "UTF-8"
    
    ' Read file
    Content = Stream.LoadFileAsText("C:\\data\\test.txt", "UTF-8")
    Debug.Print Content
End Sub

Example 2: Line-by-Line Read/Write Configuration File

Sub ConfigFileExample()
    Dim Stream As New cToolsStream
    
    ' Enable line mode
    Stream.UseLineMode True
    
    ' Create configuration content
    Stream.WriteLine "[Database]", 1
    Stream.WriteLine "Server=localhost", 2
    Stream.WriteLine "Port=3306", 3
    Stream.WriteLine "Database=mydb", 4
    Stream.WriteLine "", 5
    Stream.WriteLine "[Settings]", 6
    Stream.WriteLine "DebugMode=True", 7
    Stream.WriteLine "Timeout=30", 8
    
    ' Save configuration
    Stream.SaveFileAsText "C:\\data\\app.ini", , "UTF-8"
    
    ' Read configuration
    Stream.LoadFileAsText "C:\\data\\app.ini", "UTF-8"
    
    Dim i As Long
    For i = 1 To 8
        Debug.Print "Line " & i & ": " & Stream.ReadLine(i)
    Next i
End Sub

Example 3: Modify Configuration File

Sub ModifyConfigExample()
    Dim Stream As New cToolsStream
    
    ' Enable line mode and load file
    Stream.UseLineMode True
    Stream.LoadFileAsText "C:\\data\\app.ini", "UTF-8"
    
    ' Find and modify specific line
    Dim i As Long
    For i = 1 To Stream.LineData.Count
        Dim Line As String
        Line = Stream.ReadLine(i)
        
        ' Modify port number
        If Left(Line, 5) = "Port=" Then
            Stream.WriteLine "Port=5432", i
            Debug.Print "Modified line " & i
        End If
    Next i
    
    ' Save modification
    Stream.SaveFileAsText "C:\\data\\app.ini", , "UTF-8"
End Sub

Example 4: Binary File Processing

Sub BinaryFileExample()
    Dim Stream As New cToolsStream
    Dim InData() As Byte
    Dim OutData() As Byte
    
    ' Load binary file
    If Not Stream.LoadFileAsBinary("C:\\data\\input.bin", InData) Then
        Debug.Print "Load failed: " & Stream.LastError
        Exit Sub
    End If
    
    Debug.Print "Original file size: " & UBound(InData) + 1 & " bytes"
    
    ' Process data (e.g., simple encryption - XOR each byte with 0xFF)
    ReDim OutData(UBound(InData))
    Dim i As Long
    For i = 0 To UBound(InData)
        OutData(i) = InData(i) Xor &HFF
    Next i
    
    ' Save processed data
    If Not Stream.SaveFileAsBinary("C:\\data\\output.bin", OutData) Then
        Debug.Print "Save failed: " & Stream.LastError
        Exit Sub
    End If
    
    Debug.Print "Binary processing completed"
End Sub

Example 5: File Encoding Conversion

Sub EncodingConversionExample()
    Dim Stream As New cToolsStream
    Dim Content As String
    
    ' Read ANSI file
    Content = Stream.LoadFileAsText("C:\\data\\ansi.txt", "GBK")
    Debug.Print "Original: " & Content
    
    ' Save as UTF-8
    Stream.SaveFileAsText "C:\\data\\utf8.txt", Content, "UTF-8"
    
    Debug.Print "Encoding conversion completed: ANSI -> UTF-8"
End Sub

---

Notes

1. Encoding Support: ADO Stream supports encodings including UTF-8, UTF-16, ANSI, GBK, etc.
2. Empty Value Handling: ADO Stream cannot write empty strings, internally auto-converts to space
3. Resource Release: Stream is automatically closed when class terminates, but explicit resource management is recommended
4. Large Files: Binary mode is suitable for handling large files, but will consume memory (entire file loaded into array)
5. Error Handling: Binary operations return boolean indicating success/failure, error message in LastError