Tools - 文件系统工具类

详细文档： 每个类都有独立的详细文档，包含完整的成员说明和示例代码：
cToolsFso.md - 文件系统工具类
cFileIO.md - API 文件操作类
cFileEx.md - VB 原生文件操作类
cToolsStream.md - ADO Stream 文件操作类
ToolsFso.md - FSO 模块

cToolsFso - 文件系统工具

概述

提供文件路径处理、自动补全、目录创建等功能。

属性

Inst

返回 Scripting.FileSystemObject 实例。

Public Inst As New Scripting.FileSystemObject

示例：

' 使用 Inst 访问 FSO 功能
Dim Folder As Scripting.Folder
Set Folder = VBMAN.ToolsFso.Inst.GetFolder("C:\\MyFolder")

Dim File As Scripting.File
Set File = VBMAN.ToolsFso.Inst.GetFile("C:\\file.txt")

路径处理

IsFullPath

检查路径是否为完整路径（包含盘符）。

Public Function IsFullPath(Path As String) As Boolean

返回值：

True - 是相对路径（不包含 :\）
False - 是绝对路径

示例：

Debug.Print VBMAN.ToolsFso.IsFullPath("C:\\test.txt")  ' False（是相对路径的判断，实际为完整路径）
Debug.Print VBMAN.ToolsFso.IsFullPath("test.txt")      ' True（是相对路径的判断，实际为相对路径）

AutoCompleteFullPath

自动补全为完整路径（相对路径转为绝对路径）。

Public Function AutoCompleteFullPath(Path As String, Optional IsFile As Boolean) As String

参数：

参数名	类型	说明
`Path`	String	源路径
`IsFile`	Boolean	是否是文件路径

示例：

Dim FullPath As String
FullPath = VBMAN.ToolsFso.AutoCompleteFullPath("data\\config.ini")
' 结果: C:\\MyApp\\data\\config.ini

ClearSpan

清理路径中的多余斜杠，统一为反斜杠。

Public Function ClearSpan(Path As String, Optional IsFile As Boolean) As String

示例：

Debug.Print VBMAN.ToolsFso.ClearSpan("C:\\\\temp\\\\file.txt")
' 输出: C:\\temp\\file.txt

Debug.Print VBMAN.ToolsFso.ClearSpan("C://temp//folder//", False)
' 输出: C:\\temp\\folder\\

目录操作

AutoMakeDir

自动创建目录（如果不存在）。

Public Function AutoMakeDir(ByVal Path As String, Optional IsFile As Boolean) As String

参数：

参数名	类型	说明
`Path`	String	路径
`IsFile`	Boolean	是否是文件路径（为 True 时会提取目录部分）

返回值：

创建后的目录路径。

示例：

' 创建目录
VBMAN.ToolsFso.AutoMakeDir "C:\\MyApp\\Logs"

' 如果是文件路径，自动提取目录部分创建
VBMAN.ToolsFso.AutoMakeDir "C:\\MyApp\\Logs\\app.log", True
' 创建 C:\\MyApp\\Logs 目录

应用程序路径

AppPath

获取应用程序路径（自动处理 IDE 和编译后的路径差异）。

Public Function AppPath(Optional ByVal Path As String) As String

说明：

IDE 环境返回: App.Path & "\..\dist\EXE\"
编译后返回: App.Path & "\"

示例：

' IDE 环境: C:\\MyProject\\..\\dist\\EXE\\
' 编译后: C:\\Program Files\\MyApp\\

Dim ConfigPath As String
ConfigPath = VBMAN.ToolsFso.AppPath("config.ini")
Debug.Print ConfigPath

文件名处理

MakeNewFileFulPath

生成新的文件完整路径（添加后缀）。

Public Function MakeNewFileFulPath(FileSrc As String, AppendFix As String, Optional JoinStr As String = "_") As String

参数：

参数名	类型	说明
`FileSrc`	String	源文件路径
`AppendFix`	String	要添加的后缀
`JoinStr`	String	连接符（默认 "_"）

示例：

Dim NewPath As String

NewPath = VBMAN.ToolsFso.MakeNewFileFulPath("C:\\file.txt", "backup")
' 输出: file_backup.txt

NewPath = VBMAN.ToolsFso.MakeNewFileFulPath("C:\\data\\report.pdf", "2024", "-")
' 输出: report-2024.pdf

cFileIO - 高级文件操作（API 实现）

概述

使用 Windows CreateFile API 实现的高级文件操作，支持大文件（>2GB）。

属性

属性	说明
`IsOpen`	文件是否已打开（Boolean，只读）
`FilePath`	当前文件路径（String，只读）
`LastError`	最后一次错误信息（String，只读）
`FileSize`	文件大小（Currency，单位字节，只读）
`BufferSize`	当前缓冲区字节数（Long，只读）

文件打开/关闭

OpenFile

打开文件，返回 Me 支持链式调用。

Public Function OpenFile(ByVal FilePath As String, Optional ByVal AccessMode As String = "RW") As cFileIO

参数：

参数名	类型	说明
`FilePath`	String	文件路径
`AccessMode`	String	访问模式："R"=只读, "W"=只写, "RW"=读写(默认)

示例：

' 只读方式打开
VBMAN.FileIO.OpenFile "C:\\data.txt", "R"

' 读写方式打开
VBMAN.FileIO.OpenFile "C:\\data.txt", "RW"

' 链式调用
Dim Content As String
Content = VBMAN.FileIO.OpenFile("C:\\data.txt").ReadData().ReturnText()

CloseFile

关闭文件。

Public Sub CloseFile()

示例：

VBMAN.FileIO.CloseFile

缓冲区操作

ClearBuffer

清空内部缓冲区。

Public Function ClearBuffer() As cFileIO

SetBuffer

用外部字节数组填充缓冲区。

Public Function SetBuffer(Data() As Byte) As cFileIO

示例：

Dim Bytes() As Byte
Bytes = StrConv("Hello", vbFromUnicode)

VBMAN.FileIO.SetBuffer Bytes

AppendBuffer

追加字节到缓冲区。

Public Function AppendBuffer(Data() As Byte) As cFileIO

示例：

Dim Bytes1() As Byte, Bytes2() As Byte
Bytes1 = StrConv("Hello", vbFromUnicode)
Bytes2 = StrConv(" World", vbFromUnicode)

VBMAN.FileIO.SetBuffer(Bytes1).AppendBuffer Bytes2

SetBufferText

用字符串填充缓冲区（默认 UTF-8）。

Public Function SetBufferText(ByVal Text As String, Optional ByVal CharSet As String = "UTF-8") As cFileIO

示例：

VBMAN.FileIO.SetBufferText "Hello World", "UTF-8"

数据读取

ReadData

将文件指定范围读入内部缓冲区。

Public Function ReadData(Optional ByVal StartPos As Long = -1, Optional ByVal EndPos As Long = -1) As cFileIO

参数：

参数名	类型	说明
`StartPos`	Long	起始位置（0-based），-1表示从头开始
`EndPos`	Long	结束位置（0-based），-1表示读到末尾

示例：

' 读取整个文件
VBMAN.FileIO.OpenFile("C:\\data.txt").ReadData

' 读取指定范围
VBMAN.FileIO.OpenFile("C:\\data.txt").ReadData 0, 1023  ' 读取前1KB

' 链式调用读取并获取文本
Dim Text As String
Text = VBMAN.FileIO.OpenFile("C:\\data.txt").ReadData().ReturnText()

数据返回

ReturnText

返回缓冲区内容为文本。

Public Function ReturnText(Optional ByVal CharSet As String = "UTF-8") As String

示例：

Dim Text As String
VBMAN.FileIO.OpenFile("C:\\utf8.txt").ReadData()
Text = VBMAN.FileIO.ReturnText("UTF-8")

ReturnBytes

返回字节数组（副本）。

Public Function ReturnBytes() As Byte()

示例：

Dim Bytes() As Byte
VBMAN.FileIO.OpenFile("C:\\data.bin").ReadData()
Bytes = VBMAN.FileIO.ReturnBytes()

ReturnBase64

返回 Base64 编码字符串。

Public Function ReturnBase64() As String

示例：

Dim Base64 As String
VBMAN.FileIO.OpenFile("C:\\image.png").ReadData()
Base64 = VBMAN.FileIO.ReturnBase64()

数据写入

SaveData

将内部缓冲区写入文件。

Public Function SaveData(Optional ByVal FilePath As String, Optional ByVal IsAppend As Boolean = False) As cFileIO

参数：

参数名	类型	说明
`FilePath`	String	目标路径，为空则使用当前打开的文件
`IsAppend`	Boolean	False=覆盖(默认), True=追加

示例：

' 覆盖写入
VBMAN.FileIO.SetBufferText("Hello World").SaveData "C:\\output.txt"

' 追加写入
VBMAN.FileIO.SetBufferText("New Line").SaveData "C:\\log.txt", True

' 写入当前打开的文件
VBMAN.FileIO.OpenFile("C:\\data.txt", "RW").SetBufferText("Content").SaveData

完整示例

Private Sub FileIODemo()
    ' 读取文本文件
    Dim Content As String
    Content = VBMAN.FileIO.OpenFile("C:\\input.txt").ReadData().ReturnText()
    Debug.Print Content
    
    ' 读取并转换
    Dim Base64 As String
    Base64 = VBMAN.FileIO.OpenFile("C:\\image.png").ReadData().ReturnBase64()
    
    ' 写入文件
    VBMAN.FileIO.SetBufferText("Hello World").SaveData "C:\\output.txt"
    
    ' 追加内容
    VBMAN.FileIO.SetBufferText("Line 1" & vbCrLf).SaveData "C:\\log.txt", True
    VBMAN.FileIO.SetBufferText("Line 2" & vbCrLf).SaveData "C:\\log.txt", True
    
    ' 复制文件（分块读取大文件）
    With VBMAN.FileIO
        .OpenFile "C:\\largefile.zip"
        Dim FileLen As Currency
        FileLen = .FileSize
        
        ' 分2MB块读取
        Dim Pos As Long
        For Pos = 0 To FileLen Step 2097152
            .ReadData Pos, Pos + 2097151
            .SaveData "C:\\copy.zip", True
        Next Pos
    End With
End Sub

cFileEx - 高级文件操作（Open 语句实现）

概述

使用 VB 原生 Open 语句实现的文件操作，兼容性好，接口与 cFileIO 保持一致。

与 cFileIO 的区别

特性	cFileIO	cFileEx
实现方式	CreateFile API	VB Open 语句
大文件支持	>2GB	受限于 VB
兼容性	需要 Windows API	原生 VB，兼容性好
性能	高	一般

属性

与 cFileIO 相同：

IsOpen - 文件是否已打开
FilePath - 当前文件路径
LastError - 最后一次错误信息
FileSize - 文件大小
BufferSize - 当前缓冲区字节数

方法

与 cFileIO 基本相同，额外支持：

SetBufferBase64

用 Base64 字符串填充缓冲区。

Public Function SetBufferBase64(ByVal Base64String As String) As cFileEx

示例：

VBMAN.FileEx.SetBufferBase64 "SGVsbG8gV29ybGQ="

SetBufferHex

用 Hex 字符串填充缓冲区。

Public Function SetBufferHex(ByVal HexString As String, Optional ByVal Separator As String = " ") As cFileEx

示例：

VBMAN.FileEx.SetBufferHex "48 65 6C 6C 6F"
VBMAN.FileEx.SetBufferHex "48656C6C6F", ""  ' 无分隔符

SetBufferBinString

用二进制字符串填充缓冲区。

Public Function SetBufferBinString(ByVal BinString As String, Optional ByVal Separator As String = " ") As cFileEx

示例：

VBMAN.FileEx.SetBufferBinString "01001000 01100101 01101100 01101100 01101111"

ReturnHex

返回 Hex 编码字符串。

Public Function ReturnHex(Optional ByVal Separator As String = " ") As String

示例：

VBMAN.FileEx.OpenFile("C:\\data.bin").ReadData()
Debug.Print VBMAN.FileEx.ReturnHex(" ")  ' 输出: 48 65 6C 6C 6F
Debug.Print VBMAN.FileEx.ReturnHex("")   ' 输出: 48656C6C6F

ReturnBinString

返回二进制字符串。

Public Function ReturnBinString(Optional ByVal Separator As String = " ") As String

示例：

Debug.Print VBMAN.FileEx.ReturnBinString(" ")  ' 输出: 01001000 01100101...

cToolsStream - 流式文件操作

概述

基于 ADODB.Stream 的文件流操作，支持按行读写、多种编码。

属性

属性	类型	说明
`Inst`	ADODB.Stream	Stream 实例
`LastError`	String	最后错误信息
`UseLine`	Boolean	是否启用按行模式
`LineData`	cCollection	行数据集合
`LineNumber`	Long	当前行号

方法

UseLineMode

设置是否启用按行读写模式（链式调用）。

Public Function UseLineMode(v As Boolean) As cToolsStream

示例：

VBMAN.ToolsStream.UseLineMode(True)

LoadFileAsText

加载文本文件。

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

示例：

Dim Content As String
Content = VBMAN.ToolsStream.LoadFileAsText("test.txt", "UTF-8")

SaveFileAsText

保存文本文件。

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

示例：

' 直接保存数据
VBMAN.ToolsStream.SaveFileAsText "output.txt", "Hello World", "UTF-8"

' 使用按行模式保存
VBMAN.ToolsStream.UseLineMode(True)
VBMAN.ToolsStream.WriteLine "Line 1"
VBMAN.ToolsStream.WriteLine "Line 2"
VBMAN.ToolsStream.SaveFileAsText "output.txt", , "UTF-8"

LoadFileAsBinary

以二进制方式加载文件。

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

示例：

Dim Data() As Byte
VBMAN.ToolsStream.LoadFileAsBinary "image.png", Data

SaveFileAsBinary

以二进制方式保存文件。

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

示例：

Dim Data() As Byte
' ... 填充 Data
VBMAN.ToolsStream.SaveFileAsBinary "output.bin", Data

ReadLine

读取一行（需启用按行模式）。

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

参数：

参数名	类型	说明
`Line`	Long	指定行号，0表示当前行

示例：

' 按行读取文件
With VBMAN.ToolsStream.UseLineMode(True)
    .LoadFileAsText "log.txt", "UTF-8"
    
    Dim Line As String
    Line = .ReadLine(1)  ' 读取第1行
    Debug.Print Line
    
    Line = .ReadLine()   ' 读取下一行（自动递增）
    Debug.Print Line
End With

WriteLine

写入一行（需启用按行模式）。

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

示例：

' 按行写入文件
With VBMAN.ToolsStream.UseLineMode(True)
    .WriteLine "第一行内容"
    .WriteLine "第二行内容"
    .WriteLine "第三行内容", 10  ' 写入第10行
    .SaveFileAsText "output.txt", , "UTF-8"
End With

完整示例

Private Sub FileOperationsDemo()
    ' ========== cToolsFso 示例 ==========
    
    ' 创建目录
    VBMAN.ToolsFso.AutoMakeDir "C:\\MyApp\\Logs"
    
    ' 获取应用路径
    Dim AppPath As String
    AppPath = VBMAN.ToolsFso.AppPath("config.ini")
    
    ' 生成备份文件名
    Dim BackupName As String
    BackupName = VBMAN.ToolsFso.MakeNewFileFulPath("report.pdf", "backup")
    
    ' ========== cFileIO 示例 ==========
    
    ' 读取大文件
    Dim LargeFileContent As String
    With VBMAN.FileIO
        .OpenFile "C:\\largefile.bin"
        LargeFileContent = .ReadData().ReturnBase64()
    End With
    
    ' 写入文件
    VBMAN.FileIO.SetBufferText("Hello World").SaveData "C:\\test.txt"
    
    ' ========== cFileEx 示例 ==========
    
    ' Hex 操作
    VBMAN.FileEx.SetBufferHex "48 65 6C 6C 6F"
    VBMAN.FileEx.SaveData "C:\\hex_test.bin"
    
    ' ========== cToolsStream 示例 ==========
    
    ' 按行处理配置文件
    With VBMAN.ToolsStream.UseLineMode(True)
        .LoadFileAsText "config.ini", "UTF-8"
        
        Dim i As Long
        For i = 1 To 10
            Debug.Print "Line " & i & ": " & .ReadLine(i)
        Next i
    End With
End Sub

Tools - 文件系统工具类 ​

cToolsFso - 文件系统工具 ​

概述 ​

属性 ​

Inst ​

路径处理 ​

IsFullPath ​

AutoCompleteFullPath ​

ClearSpan ​

目录操作 ​

AutoMakeDir ​

应用程序路径 ​

AppPath ​

文件名处理 ​

MakeNewFileFulPath ​

cFileIO - 高级文件操作（API 实现） ​

概述 ​

属性 ​

文件打开/关闭 ​

OpenFile ​

CloseFile ​

缓冲区操作 ​

ClearBuffer ​

SetBuffer ​

AppendBuffer ​

SetBufferText ​

数据读取 ​

ReadData ​

数据返回 ​

ReturnText ​

ReturnBytes ​

ReturnBase64 ​

数据写入 ​

SaveData ​

完整示例 ​

cFileEx - 高级文件操作（Open 语句实现） ​

概述 ​

与 cFileIO 的区别 ​

属性 ​

方法 ​

SetBufferBase64 ​

SetBufferHex ​

SetBufferBinString ​

ReturnHex ​

ReturnBinString ​

cToolsStream - 流式文件操作 ​

概述 ​

属性 ​

方法 ​

UseLineMode ​

LoadFileAsText ​

SaveFileAsText ​

LoadFileAsBinary ​

SaveFileAsBinary ​

ReadLine ​

WriteLine ​

完整示例 ​

Tools - 文件系统工具类

cToolsFso - 文件系统工具

概述

属性

Inst

路径处理

IsFullPath

AutoCompleteFullPath

ClearSpan

目录操作

AutoMakeDir

应用程序路径

AppPath

文件名处理

MakeNewFileFulPath

cFileIO - 高级文件操作（API 实现）

概述

属性

文件打开/关闭

OpenFile

CloseFile

缓冲区操作

ClearBuffer

SetBuffer

AppendBuffer

SetBufferText

数据读取

ReadData

数据返回

ReturnText

ReturnBytes

ReturnBase64

数据写入

SaveData

完整示例

cFileEx - 高级文件操作（Open 语句实现）

概述

与 cFileIO 的区别

属性

方法

SetBufferBase64

SetBufferHex

SetBufferBinString

ReturnHex

ReturnBinString

cToolsStream - 流式文件操作

概述

属性

方法

UseLineMode

LoadFileAsText

SaveFileAsText

LoadFileAsBinary

SaveFileAsBinary

ReadLine

WriteLine

完整示例