# base64 库模块帮助文档
说明
base64 支持库编解码的速度非常快，但程序会增加几十 KB 的大小。
一般情况建议使用 crypt.encodeBin , crypt.decodeBin 进行 Base64 编码或解码。
因为很多库引用了 crypt 库，这通常可以减少程序体积。
crypt.encodeBin , crypt.decodeBin 其实也很快，
例如编码一个图像文件基本感觉不到延时，这时候用 base64 支持库去优化意义就不大。
但如果是频繁地密集地处理较大的数据，使用 base64 支持库可以显著地提升性能。
此支持库基于开源项目
https://github.com/aklomp/base64
引用的 libbase64.dll 使用 `\lib\base64\.res\build.aardio` 编译，关键参数如下：
~~~aardio
var gcc = process.gcc("/");
gcc.exec("make SSSE3_CFLAGS=-mssse3 SSE41_CFLAGS=-msse4.1 SSE42_CFLAGS=-msse4.2 AVX_CFLAGS=-mavx AVX2_CFLAGS=-mavx2");
~~~
## base64 成员列表 #
高性能编解码库。
普通 base64 编码可以使用 crypt.encodeBin，解码可以使用 crypt.decodeBin。
base64 库则利用现代 CPU 指令集优化提供了更好的编解码性能
### base64.decode(base64String) #
解码参数 @base64String 指定的 Base64 字符串。
成功返回解码后的数据（非空数据为 buffer 类型），失败返回 null,错误信息。
传入空字符串或长度为 0 会返回 null 值。
参数：base64 编码的字符串或 buffer 。
### base64.decodeBuilder() #
[返回对象:StringBuilderObject](https://www.aardio.com/zh-cn/docs/library-reference/string/builder.html#StringBuilderObject)
### base64.decodeBuilder(base64String) #
解码参数 @base64String 指定的 Base64 字符串。
成功返回包含解码数据的 string.builder 对象，失败返回 null,错误信息。
传入空字符串会返回 null 值。
参数：base64 编码的字符串或 buffer 。
参数 @2 可选指定 CPU 指令集（数值）,仅用于测试，生产环境不要指定。
### base64.decodeToFile(base64String,path) #
解码参数 @base64String 指定的 Base64 字符串，
并保存到参数 @path 指定路径的文件中。
成功返回写入长度，失败返回 null 错误信息。
### base64.decoder() #
创建流式解码器对象。
[返回对象:Base64DecoderObject](#Base64DecoderObject)
### base64.encode(data,size) #
编码字符串为 base64 格式。
- 参数 @data：要编码的字符串、buffer 或结构体对象。
- 参数 @size 用于指定要编码的数据长度，可选参数。
如果不指定参数 @size 函数则会自动检查 @data 的类型并获取长度。
否则不会检查参数 @data 的类型，此时 @data 可以传入字符串、buffer、结构体、指针），
如果传入其他类型（例如数值）会导致内存错误。
传入空字符串或长度为 0 会返回空字符串。
### base64.encodeBuilder() #
[返回对象:StringBuilderObject](https://www.aardio.com/zh-cn/docs/library-reference/string/builder.html#StringBuilderObject)
### base64.encodeBuilder(data,size,flags) #
编码输入数据为 base64 格式。
返回包含编码数据的 string.builder 对象。
- 参数 @data：要编码的字符串、buffer 或结构体对象。
- 参数 @size 用于指定要编码的数据长度，可选参数。
如果不指定参数 @size 函数则会自动检查 @data 的类型并获取长度。
否则不会检查参数 @data 的类型，此时 @data 可以传入字符串、buffer、结构体、指针），
如果传入其他类型（例如数值）会导致内存错误。
- 可选用参数 @flags 可选指定 CPU 指令集（数值）,
这个参数仅用于测试 CPU，生产环境不应指定（默认会自动检测优化）。
### base64.encodeBuilderFromFile(path) #
读取参数 @path 指定路径的文件并编码为 base64 格式。
返回包含编码数据的 string.builder 对象。
### base64.encodeFromFile(path) #
读取参数 @path 指定路径的文件并编码为 base64 格式。
返回包含编码数据的字符串。
### base64.encoder() #
创建流式编码器对象。
[返回对象:Base64EncoderObject](#Base64EncoderObject)
### base64.is() #
检测参数 @1 指定的字符串（或 buffer）的长度与包含的字符是特征是否符合 Base64 编码特征。
此函数使用表达式 `type.isString(s) ? (#s % 4 == 0) ? string.find(s,"^[\a\d/+]+={0,2}$")`
进行检测。
## Base64DecoderObject 成员列表 #
### Base64DecoderObject.final() #
完成解码并返回结果，返回值为 buffer 类型。
如果解码数据为空则返回 null 值（ aardio 中不存在长度为 0 的 buffer ）。
此函数会释放 base64.decoder 对象。
### Base64DecoderObject.finalBuilder() #
完成解码并返回包含所有解码数据的 string.builder 对象。
此函数会释放 base64.decoder 对象。
[返回对象:StringBuilderObject](https://www.aardio.com/zh-cn/docs/library-reference/string/builder.html#StringBuilderObject)
### Base64DecoderObject.outBuilder #
存放输出数据的 string.builder 对象。
可用 string 方法读取字符串，buffer 方法读取缓冲区，pointer 方法读取指针。
可用 size 方法读取当前暂存的数据长度。
如果读取或存储了数据可调用 resize 方法将长度设为 0 以清空输出缓冲区。
[返回对象:StringBuilderObject](https://www.aardio.com/zh-cn/docs/library-reference/string/builder.html#StringBuilderObject)
### Base64DecoderObject.read() #
读取当前解码数据并清空输出缓冲区。
如果读取到数据则返回值为 buffer 类型，数据为空时返回 null 值。
### Base64DecoderObject.write(base64String) #
写入要解码的 Base64 字符串。
如果输入错误的编码此函数会抛出异常，否则返回自身以支持链式调用。
## Base64EncoderObject 成员列表 #
### Base64EncoderObject.final() #
完成编码并返回结果，返回值为字符串类型。
如果输入数据不完整会返回 null, 错误信息。
此函数执行成功会释放 base64.encoder 对象。
### Base64EncoderObject.finalBuilder() #
完成编码并返回包含所有编码数据的 string.builder 对象。
如果输入数据不完整会返回 null, 错误信息。
此函数执行成功会释放 base64.encoder 对象。
[返回对象:StringBuilderObject](https://www.aardio.com/zh-cn/docs/library-reference/string/builder.html#StringBuilderObject)
### Base64EncoderObject.outBuilder #
存放输出数据的 string.builder 对象。
可用 string 方法读取字符串，buffer 方法读取缓冲区，pointer 方法读取指针。
可用 size 方法读取当前暂存的数据长度。
如果读取或存储了数据可调用 resize 方法将长度设为 0 以清空输出缓冲区。
[返回对象:StringBuilderObject](https://www.aardio.com/zh-cn/docs/library-reference/string/builder.html#StringBuilderObject)
### Base64EncoderObject.read() #
读取当前编码数据并清空输出缓冲区。
如果读取到数据则返回值为字符串，数据为空时返回 null 值。
### Base64EncoderObject.write(data,size) #
写入要编码的数据，返回自身以支持链式调用。
- 参数 @data：要编码的字符串、buffer 或结构体对象。
- 参数 @size 用于指定要编码的数据长度，可选参数。
如果不指定参数 @size 函数则会自动检查 @data 的类型并获取长度。
否则不会检查参数 @data 的类型，此时 @data 可以传入字符串、buffer、结构体、指针），
如果传入其他类型（例如数值）会导致内存错误。
每次写入的字节长度建议对齐 4 字节，如果`写入长度 % 4` 不为 0 时则会缓存输入数据直到满足条件