cToolsStream 类

基于 ADODB.Stream 的流式文件操作类，支持文本和二进制数据读写。

说明

cToolsStream 是对 ADODB.Stream 对象的封装，提供简化的文件读写接口。支持按行读写模式，适合处理文本配置文件。

引用库：

Microsoft ActiveX Data Objects 2.8 Library (msado28.tlb)

特点：

支持文本和二进制两种模式
支持按行读写（将文件内容按行分割存储）
自动处理编码（UTF-8、ANSI 等）

属性

属性名	类型	说明
`Inst`	`ADODB.Stream`	ADO Stream 实例对象
`LastError`	`String`	最后一次错误信息
`LineNumber`	`Long`	当前行号（按行模式下使用）
`UseLine`	`Boolean`	是否启用按行读写模式
`LineData`	`cCollection`	按行存储的数据集合
`Txt`	`cToolsStr`	字符串工具实例

方法

UseLineMode

设置是否启用按行读写模式。

语法：

Public Function UseLineMode(v As Boolean) As cToolsStream

参数：

参数	类型	说明
`v`	`Boolean`	`True`=启用按行模式, `False`=禁用

返回值：

返回自身实例，支持链式调用

说明：

启用后，LineData 集合将作为数据主体
Inst 中保存的是原始文件内容

示例：

Dim Stream As New cToolsStream

' 启用按行模式
Stream.UseLineMode True

ReadLine

从指定行读入一行内容。

语法：

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

参数：

参数	类型	说明
`Line`	`Long`	可选。指定行号（1-based），不提供则使用 `LineNumber`

返回值：

该行内容字符串

异常：

未启用按行模式时抛出错误

说明：

读取后 LineNumber 自动 +1
如果提供 Line 参数，则设置 LineNumber = Line

示例：

Dim Stream As New cToolsStream
Stream.UseLineMode True

' 加载文件（会自动分割为行）
Stream.LoadFileAsText "C:\\data\\config.ini", "UTF-8"

' 逐行读取
Dim Line1 As String
Line1 = Stream.ReadLine()  ' 读取第 1 行

Dim Line5 As String
Line5 = Stream.ReadLine(5)  ' 读取第 5 行

WriteLine

向指定行写入内容。

语法：

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

参数：

参数	类型	说明
`Text`	`String`	要写入的内容
`Line`	`Long`	可选。指定行号，不提供则使用 `LineNumber`

返回值：

True - 写入成功

异常：

未启用按行模式时抛出错误

说明：

写入后 LineNumber 自动 +1
如果行号已存在，会替换原有内容

示例：

Dim Stream As New cToolsStream
Stream.UseLineMode True

' 写入多行
Stream.WriteLine "[Section1]", 1
Stream.WriteLine "Key1=Value1", 2
Stream.WriteLine "Key2=Value2", 3

' 保存文件
Stream.SaveFileAsText "C:\\data\\config.ini", , "UTF-8"

LoadFileAsText

以文本模式加载文件。

语法：

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

参数：

参数	类型	说明
`FileName`	`String`	文件路径
`CharSet`	`String`	可选。字符编码，默认为 `UTF-8`

返回值：

文件内容字符串

说明：

如果启用了按行模式，内容会自动按行分割存入 LineData
加载后 LineNumber 重置为 1

示例：

Dim Stream As New cToolsStream
Dim Content As String

' 基本加载
Content = Stream.LoadFileAsText("C:\\data\\readme.txt", "UTF-8")
Debug.Print Content

' 按行模式加载
Stream.UseLineMode True
Content = Stream.LoadFileAsText("C:\\data\\config.ini", "UTF-8")
' 现在可以使用 ReadLine 访问各行
Debug.Print Stream.ReadLine(1)

SaveFileAsText

以文本模式保存文件。

语法：

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

参数：

参数	类型	说明
`FileName`	`String`	目标文件路径
`Data`	`Variant`	可选。要保存的数据，不提供则使用 `LineData`（按行模式）或 `Inst`
`CharSet`	`String`	可选。字符编码，默认为 `UTF-8`

返回值：

True - 保存成功

说明：

文件已存在会覆盖
按行模式下，如果不提供 Data，自动使用 LineData 集合

示例：

Dim Stream As New cToolsStream

' 直接保存字符串
Stream.SaveFileAsText "C:\\data\\output.txt", "Hello World", "UTF-8"

' 按行模式保存
Stream.UseLineMode True
Stream.WriteLine "Line 1", 1
Stream.WriteLine "Line 2", 2
Stream.SaveFileAsText "C:\\data\\lines.txt", , "UTF-8"

LoadFileAsBinary

以二进制模式加载文件。

语法：

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

参数：

参数	类型	说明
`Path`	`String`	文件路径
`OutData`	`Byte()`	输出字节数组

返回值：

True - 加载成功
False - 加载失败（错误信息在 LastError）

示例：

Dim Stream As New cToolsStream
Dim Bytes() As Byte

If Stream.LoadFileAsBinary("C:\\data\\file.bin", Bytes) Then
    Debug.Print "加载成功，字节数: " & UBound(Bytes) + 1
Else
    Debug.Print "加载失败: " & Stream.LastError
End If

SaveFileAsBinary

以二进制模式保存文件。

语法：

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

参数：

参数	类型	说明
`Path`	`String`	目标文件路径
`OutData`	`Byte()`	要保存的字节数组

返回值：

True - 保存成功
False - 保存失败（错误信息在 LastError）

示例：

Dim Stream As New cToolsStream
Dim Bytes() As Byte

' 填充数据
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 "保存成功"
Else
    Debug.Print "保存失败: " & Stream.LastError
End If

使用示例

示例 1：简单的文本文件读写

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

示例 2：按行读写配置文件

Sub ConfigFileExample()
    Dim Stream As New cToolsStream
    
    ' 启用按行模式
    Stream.UseLineMode True
    
    ' 创建配置内容
    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
    
    ' 保存配置
    Stream.SaveFileAsText "C:\\data\\app.ini", , "UTF-8"
    
    ' 读取配置
    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

示例 3：修改配置文件

Sub ModifyConfigExample()
    Dim Stream As New cToolsStream
    
    ' 启用按行模式并加载文件
    Stream.UseLineMode True
    Stream.LoadFileAsText "C:\\data\\app.ini", "UTF-8"
    
    ' 查找并修改特定行
    Dim i As Long
    For i = 1 To Stream.LineData.Count
        Dim Line As String
        Line = Stream.ReadLine(i)
        
        ' 修改端口号
        If Left(Line, 5) = "Port=" Then
            Stream.WriteLine "Port=5432", i
            Debug.Print "已修改第 " & i & " 行"
        End If
    Next i
    
    ' 保存修改
    Stream.SaveFileAsText "C:\\data\\app.ini", , "UTF-8"
End Sub

示例 4：二进制文件处理

Sub BinaryFileExample()
    Dim Stream As New cToolsStream
    Dim InData() As Byte
    Dim OutData() As Byte
    
    ' 加载二进制文件
    If Not Stream.LoadFileAsBinary("C:\\data\\input.bin", InData) Then
        Debug.Print "加载失败: " & Stream.LastError
        Exit Sub
    End If
    
    Debug.Print "原始文件大小: " & UBound(InData) + 1 & " 字节"
    
    ' 处理数据（例如：简单加密 - 每个字节 XOR 0xFF）
    ReDim OutData(UBound(InData))
    Dim i As Long
    For i = 0 To UBound(InData)
        OutData(i) = InData(i) Xor &HFF
    Next i
    
    ' 保存处理后的数据
    If Not Stream.SaveFileAsBinary("C:\\data\\output.bin", OutData) Then
        Debug.Print "保存失败: " & Stream.LastError
        Exit Sub
    End If
    
    Debug.Print "二进制处理完成"
End Sub

示例 5：文件编码转换

Sub EncodingConversionExample()
    Dim Stream As New cToolsStream
    Dim Content As String
    
    ' 读取 ANSI 文件
    Content = Stream.LoadFileAsText("C:\\data\\ansi.txt", "GBK")
    Debug.Print "原文: " & Content
    
    ' 保存为 UTF-8
    Stream.SaveFileAsText "C:\\data\\utf8.txt", Content, "UTF-8"
    
    Debug.Print "编码转换完成: ANSI -> UTF-8"
End Sub

注意事项

编码支持：ADO Stream 支持的编码包括 UTF-8、UTF-16、ANSI、GBK 等
空值处理：ADO Stream 不能写入空字符串，内部会自动转换为空格
资源释放：类终止时会自动关闭 Stream，但建议显式管理资源
大文件：二进制模式适合处理大文件，但会占用内存（整个文件读入数组）
错误处理：二进制操作返回布尔值表示成功/失败，错误信息在 LastError

AES

Hash

HMAC

cToolsStream 类

说明

属性

方法

UseLineMode

ReadLine

WriteLine

LoadFileAsText

SaveFileAsText

LoadFileAsBinary

SaveFileAsBinary

使用示例

示例 1：简单的文本文件读写

示例 2：按行读写配置文件

示例 3：修改配置文件

示例 4：二进制文件处理

示例 5：文件编码转换

注意事项

cToolsStream 类 ​

说明 ​

属性 ​

方法 ​

UseLineMode ​

ReadLine ​

WriteLine ​

LoadFileAsText ​

SaveFileAsText ​

LoadFileAsBinary ​

SaveFileAsBinary ​

使用示例 ​

示例 1：简单的文本文件读写 ​

示例 2：按行读写配置文件 ​

示例 3：修改配置文件 ​

示例 4：二进制文件处理 ​

示例 5：文件编码转换 ​

注意事项 ​

cToolsStream 类

说明

属性

方法

UseLineMode

ReadLine

WriteLine

LoadFileAsText

SaveFileAsText

LoadFileAsBinary

SaveFileAsBinary

使用示例

示例 1：简单的文本文件读写

示例 2：按行读写配置文件

示例 3：修改配置文件

示例 4：二进制文件处理

示例 5：文件编码转换

注意事项