Binary

Black2024年12月22日大约 11 分钟

Binary

概述

警告

该分类下的内容普通用户不需要了解，也不会用到。除非你有一定的计算机基础知识。

Binary分类下的内容用于处理数据流（或者叫二进制流），如文件的原始内容、网络下载的内容等。
对于已有连接器的数据源，我们可以通过已有连接器轻易的实现数据的读取，但是对于某些冷门的数据，我们可能需要自己动手实现。比如某些网站仅提供zip文件，而其中包含很多json文件，此时你可以通过该分类下的函数读取zip文件（同时你也要足够了解zip文件协议）。

注意

binary类型的值也存在流式语义，对于快速变换的数据，应该保持谨慎。

#binary

#binary(value as any) as any

将值value转为binary类型值。
参数value可以是数字形式的字节列表或base64编码后的文本。

#binary({0x41, 0x42, 0x43}

#binary("QUJD")

Binary.ApproximateLength

Binary.ApproximateLength(binary as nullable binary) as nullable number

返回二进制值binary的近似长度，如果数据源不支持近似长度则返回错误。

Binary.ApproximateLength(#binary({0x41, 0x00, 0x42, 0x00, 0x43, 0x00}))

Binary.Buffer

Binary.Buffer(binary as nullable binary) as nullable binary

在内存中缓存二进制值binary，因此它有确定的长度和顺序。

Binary.Buffer(#binary({0x41, 0x00, 0x42, 0x00, 0x43, 0x00}))

Binary.Combine

Binary.Combine(binaries as list) as binary

将多个二进制值的列表binaries组合成一个二进制值。

Binary.Combine({#binary({0x41}), #binary({0x42})})

Binary.Compress

Binary.Compress(binary as nullable binary, compressionType as number) as nullable binary

对二进制值binary使用compressionType指定的压缩方式压缩为新的二进制值。
参数compressionType用于指定压缩方式，是Compression.Type枚举值，但仅支持下面两种方式：

Compression.GZip
Compression.Deflate

Binary.ToList(
    Binary.Compress(
        #binary({0x41, 0x41, 0x41, 0x41, 0x41, 0x41}), 
        Compression.Deflate
    )
)

Binary.Decompress

Binary.Decompress(binary as nullable binary, compressionType as number) as nullable binary

对二进制值binary使用compressionType指定的压缩方式解压为新的二进制值。
参数compressionType用于指定解压方式，是Compression.Type枚举值，但仅支持下面两种方式：

Compression.GZip
Compression.Deflate

Binary.ToList(
    Binary.Decompress(
        #binary({0x73, 0x74, 0x04, 0x01, 0x00}), 
        Compression.Deflate
    )
)

Binary.From

Binary.From(value as any, optional encoding as nullable number) as nullable binary

将给定的值value转换为二进制值。
参数value可能的类型：

null：返回null。
二进制值：原样输出。
文本：使用Binary.FromText进行转换。
其他类型：返回错误。

参数encoding用于当value是文本时传递给调用的Binary.FromText函数。

Binary.From(null)

Binary.From("QUJD")

Binary.FromList

Binary.FromList(list as list) as binary

将数值列表转为二进制值。

Binary.FromList({0x41, 0x42})

Binary.FromText

Binary.FromText(
    text as nullable text, 
    optional encoding as nullable number
) as nullable binary

将文本值转换成二进制值。
参数encoding用于指定文本的编码，可以是BinaryEncoding.Type枚举值。

Binary.FromText("QQBCAEMA")

Binary.FromText("410042004300", BinaryEncoding.Hex)

Binary.InferContentType

Binary.InferContentType(source as binary) as record

推测source的MIME类型。
该函数通常用于网络应答正文的检测。
结果可能包含的字段：

Content.Type
Content.Encoding
Csv.PotentialDelimiters
Csv.PotentialPositions

Binary.InferContentType(Binary.FromText("916211", BinaryEncoding.Hex))

Binary.InferContentType(Binary.FromText("414243", BinaryEncoding.Hex))

Binary.Length

Binary.Length(binary as nullable binary) as nullable number

返回二进制值的字节数。

Binary.Length(Binary.FromText("410042006211", BinaryEncoding.Hex))

Binary.Range

Binary.Range(
    binary as binary, 
    offset as number, 
    optional count as nullable number
) as binary

从索引offset开始截取binary，共截取count个字节。
参数offset用于指定开始截取的位置，从0开始计数。该参数也可以理解为跳过前几个字节。
参数count用于指定需要截取的字节数，如果不传参或传递null，将截取offset及之后的全部。

Binary.ToList(Binary.Range(Binary.FromText("410042006211", BinaryEncoding.Hex), 2))

Binary.ToList

Binary.ToList(binary as binary) as list

将二进制值转为列表。

Binary.ToList(#binary({1, 2, 3}))

Binary.ToText

Binary.ToText(
    binary as nullable binary, 
    optional encoding as nullable number
) as nullable text

将二进制值转为文本。
参数encoding用于指定编码，是BinaryEncoding.Type枚举值。默认使用BinaryEncoding.Base64。

Binary.ToText(#binary({1, 2, 3}))

Binary.ToText(#binary({1, 2, 3}), BinaryEncoding.Hex)

Binary.View

Binary.View(binary as nullable binary, handlers as record) as binary

返回二进制值binary的视图。
该函数主要用于自定义连接器。

Binary.View(
    null,
    [
        GetLength = () => 12,
        GetStream = () => Text.ToBinary("hello world!")
    ]
)

Binary.ViewError

Binary.ViewError(errorRecord as record) as record

根据errorRecord创建修改后的错误记录，当被视图上定义的处理程序抛出时（通过Binary.View函数），它不会触发回退。
该函数主要用于自定义连接器。

Binary.ViewFunction

Binary.ViewFunction(function as function) as function

根据函数function创建视图函数，此函数可以在Binary.View函数创建的视图中进行处理。
Binary.View的OnInvoke处理程序用于为视图函数定义处理函数。
该函数主要用于自定义连接器。

BinaryFormat.7BitEncodedSignedInteger

BinaryFormat.7BitEncodedSignedInteger(binary as binary) as any

读取使用7bit可变长编码进行编码的64位有符号整数。

Binary.7BitEncodedUnsignedInteger

BinaryFormat.7BitEncodedUnsignedInteger(binary as binary) as any

读取使用7bit可变长编码进行编码的64位无符号整数。

BinaryFormat.Binary

BinaryFormat.Binary(optional length as any) as function

返回一个至少读取length个字节的函数。
参数length如果未指定，则读取全部内容。
如果调用时传递的二进制值长度小于length，将会报错。

BinaryFormat.Binary()(Binary.FromText("4142434445", BinaryEncoding.Hex))

BinaryFormat.Binary(3)(Binary.FromText("4142434445", BinaryEncoding.Hex))

BinaryFormat.Byte

BinaryFormat.Byte(binary as binary) as any

读取binary的第一个字节并使用8bit无符号整数表示。

BinaryFormat.Byte(Binary.FromText("4142434445", BinaryEncoding.Hex))

BinaryFormat.Byte(#binary({0xFF}))

BinaryFormat.ByteOrder

BinaryFormat.ByteOrder(binaryFormat as function, byteOrder as number) as function

在指定字节序byteOrder时调用binaryFormat函数。
该函数是一个闭包，即byteOrder用于确定字节序，binaryFormat函数根据字节序执行。只需要在可以带入的函数中做一个标识符检测即可。

BinaryFormat.ByteOrder(
    BinaryFormat.UnsignedInteger32, 
    ByteOrder.BigEndian
)(#binary({0, 0, 0, 1}))

BinaryFormat.Choice

BinaryFormat.Choice(
    binaryFormat as function, 
    chooseFunction as function, 
    optional type as nullable type, 
    optional combineFunction as nullable function
) as function

返回一个函数，该函数会执行：

使用binaryFormat读取出第一个值x。
将x作为参数传递给chooseFunction并得到第二个值y。
检查type指定的类型（只能是any、binary、list，当指定combineFunction时只能是any）。
将x和y作为参数传递给combineFunction并生成结果。如果未指定combineFunction，则返回y。

如果type指定list或binary类型，则系统可能会返回流式list或binary值，从而降低计算压力。

BinaryFormat.Choice(
    BinaryFormat.UnsignedInteger16, 
    (length) => BinaryFormat.List(BinaryFormat.Byte, length)
)(#binary({0, 3, 3, 4, 5, 6}))

BinaryFormat.Choice(
    BinaryFormat.UnsignedInteger16, 
    (length) => BinaryFormat.Byte, 
    type any, 
    (x, y) => x + y
)(#binary({0, 1, 3, 4, 5, 6}))

BinaryFormat.Decimal

BinaryFormat.Decimal(binary as binary) as any

读取二进制值的前16个字节并将其转换为.NET16字节的十进制（decimal）数字。默认使用大端模式。

BinaryFormat.Decimal(Binary.FromText("00000000000000000000000000000000", BinaryEncoding.Hex))

BinaryFormat.Double

BinaryFormat.Double(binary as binary) as any

读取二进制值的前8个字节并将其转换为8字节IEEE双精度浮点数。
默认使用大端模式。

BinaryFormat.Double(Binary.FromText("4000000000000000", BinaryEncoding.Hex))

BinaryFormat.Group

BinaryFormat.Group(
    binaryFormat as function, 
    group as list, 
    optional extra as nullable function, 
    optional lastKey as any
) as function

返回一个函数，该函数用于通过键的方式读取组中的内容，并以列表的形式返回读取到的内容。
参数binaryFormat是一个BinaryFormat.*函数，用于指定键值的二进制格式。
参数group是一个列表，用于指定已知项组的格式。
参数extra是一个函数，该函数为预期之后的值返回二进制格式值。如果不指定该参数，当存在预期之外的内容时将发生错误。
参数lastKey为任意值，用法未知。
参数group是若干拥有3~5个项的列表组成的列表，项功能说明：

键值：与项对应的键的值，该值在当前项中必须唯一。
项格式：与键值对应的二进制格式，各项可以具有不同的格式。
项出现次数：键值对应的内容在组中出现的次数，可以指定BinaryOccurrence.Type枚举值。如果设置为必需项，但组中不存在时会报错。
默认项值：可选。用于指定当可选或重复项的默认值。可选项默认null，重复项默认{}。
项值转换：可选。当组中存在对应值时会进行转换并作为结果返回。

// 例1
let 
    bin = #binary({
        1, 12, 
        2, 34, 
        2, 56, 
        4, 78, 
        5, 90
    }), 
    f = BinaryFormat.Group(
        BinaryFormat.Byte, 
        {
            {1, BinaryFormat.Byte, BinaryOccurrence.Required}, 
            {2, BinaryFormat.Byte, BinaryOccurrence.Repeating}, 
            {3, BinaryFormat.Byte, BinaryOccurrence.Optional}, 
            {4, BinaryFormat.Byte, BinaryOccurrence.Repeating}, 
            {6, BinaryFormat.Byte, BinaryOccurrence.Repeating, 666}
        }, 
        (x) => BinaryFormat.Byte
    )
in 
    f(bin)
/*	OUT
{
	12, 
    {34, 56}, 
    null, 
    {78}, 
    666
}
*/

// 例2
// 读取时默认为大端模式，可以单独切换到小端模式。
let 
    bin = #binary({1, 12, 2, 00, 01, 4, 01, 00, 00, 00}), 
    f = BinaryFormat.Group(
        BinaryFormat.Byte, 
        {
            {1, BinaryFormat.Byte, BinaryOccurrence.Required}, 
            {2, BinaryFormat.UnsignedInteger16, BinaryOccurrence.Optional}, 
            {3, BinaryFormat.Byte, BinaryOccurrence.Optional}, 
            {
                4, 
                BinaryFormat.ByteOrder(BinaryFormat.UnsignedInteger32, ByteOrder.LittleEndian), 
                BinaryOccurrence.Optional, 
                null, 
                (x) => x + 1
            }
        }, 
        (x) => BinaryFormat.Byte
    )
in 
    f(bin)
/*	OUT
{
	12, 
    1, 
    null, 
    2
}
*/

// 例3
// 对于键也可以设置大小端模式。
let 
    bin = #binary({
        01, 00, 12, 
        02, 00, 01, 00, 
        03, 00, 01, 00, 00, 00
    }), 
    f = BinaryFormat.Group(
        BinaryFormat.ByteOrder(BinaryFormat.UnsignedInteger16, ByteOrder.LittleEndian), 
        {
            {1, BinaryFormat.Byte, BinaryOccurrence.Required}, 
            {2, BinaryFormat.UnsignedInteger16, BinaryOccurrence.Optional}, 
            {3, BinaryFormat.ByteOrder(BinaryFormat.UnsignedInteger32, ByteOrder.LittleEndian), BinaryOccurrence.Optional}
        }, 
        (x) => BinaryFormat.Byte
    )
in 
    f(bin)
/*	OUT
{
	12, 
    256, 
    1
}
*/

BinaryFormat.Length

BinaryFormat.Length(binaryFormat as function, length as any) as function

返回一个函数，该函数会将binaryFormat限制在length长度（字节数）内。
参数binaryFormat必须是BinaryFormat.*函数。该参数中指定的读取长度如果超过length可能会报错。

BinaryFormat.Length(
    BinaryFormat.List(BinaryFormat.UnsignedInteger16), 
    4
)(#binary({65, 66, 67, 68, 69}))

Binary.ToList(
    BinaryFormat.Length(
        BinaryFormat.Binary(3), 
        4
    )(#binary({65, 66, 67, 68}))
)

BinaryFormat.List

BinaryFormat.List(binaryFormat as function, optional countOrCondition as any) as function

返回一个函数，该函数会根据binaryFormat按顺序读取二进制值，生成得结果会组成一个列表返回。
参数countOrCondition用于指定何时中止读取：

不指定：一直向后读取，直到结束。如果最后剩余的内容不够读取，可能会生成错误。需要注意的是，列表拥有流式语义，因此仅读取可以访问的项不会产生错误。
整数：将binaryFormat执行countOrCondition次，而不是字节数。如果是负数会报错。
函数：将binaryFormat生成的结果作为参数传递给countOrCondition，如果为true则继续执行，如果为false则停止执行并包含当前为false的结果并返回最终结果列表。
二进制值：必须是BinaryFormat.*函数，因为countOrCondition需要先读取若干字节，所以BinaryFormat.List会在其之后的位置开始读取执行。

BinaryFormat.List(BinaryFormat.UnsignedInteger16)(#binary({0, 1, 0, 2, 0, 3, 0}))

BinaryFormat.List(BinaryFormat.UnsignedInteger16)(#binary({0, 1, 0, 2, 0, 3, 0})){2}

BinaryFormat.List(BinaryFormat.UnsignedInteger16, 2)(#binary({1, 2, 3, 4, 5}))

BinaryFormat.List(BinaryFormat.Byte, 3)(#binary({0, 1, 2, 3, 4, 5}))

BinaryFormat.List(BinaryFormat.Byte, each _ < 3)(#binary({0, 1, 2, 3, 4, 5}))

BinaryFormat.List(
    BinaryFormat.UnsignedInteger16, 
    each _ < 3
)(#binary({0, 1, 0, 2, 0, 3, 0, 4}))

BinaryFormat.List(
    BinaryFormat.Byte, 
    BinaryFormat.UnsignedInteger16
)(#binary({0, 1, 2, 3, 4, 5}))

BinaryFormat.Null

BinaryFormat.Null(binary as binary) as any

读取零字节并返回null的二进制值。

BinaryFormat.Null(#binary({65, 0}))

BinaryFormat.Record

BinaryFormat.Record(record as record) as function

返回一个函数，该函数根据record指定的长度（字节数）截取结果并生成记录值。
参数record是形如[name = BinaryFormat.*, ...]的记录值，函数返回形如[name = ..., ...]的结果。

BinaryFormat.Record(
    [
        A = BinaryFormat.SignedInteger32, 
        B = BinaryFormat.Byte
    ]
)(#binary({0, 0, 0, 66, 77}))

BinaryFormat.ByteOrder(
    BinaryFormat.Record(
        [
            A = BinaryFormat.SignedInteger32, 
            B = BinaryFormat.Byte
        ]
    ), 
    ByteOrder.LittleEndian
)(#binary({66, 0, 0, 0, 77}))

BinaryFormat.Record(
    [
        A = BinaryFormat.Text(4), 
        B = BinaryFormat.Byte
    ]
)(#binary({65, 66, 67, 68, 77}))

BinaryFormat.SignedInteger16

BinaryFormat.SignedInteger16(binary as binary) as any

读取二进制值的前2个字节并将其转换为16位有符号整数。
默认使用大端模式。

BinaryFormat.SignedInteger16(#binary({128, 1}))

BinaryFormat.SignedInteger32

BinaryFormat.SignedInteger32(binary as binary) as any

读取二进制值的前4个字节并将其转换为32位有符号整数。
默认使用大端模式。

BinaryFormat.SignedInteger32(#binary({128, 0, 0, 1}))

BinaryFormat.SignedInteger64

BinaryFormat.SignedInteger64(binary as binary) as any

读取二进制值的前8个字节并将其转换为32位有符号整数。
默认使用大端模式。

BinaryFormat.SignedInteger64(#binary({128, 0, 0, 0, 0, 0, 0, 1}))

BinaryFormat.Single

BinaryFormat.Single(binary as binary) as any

读取二进制值的前4个字节并将其转换为4字节IEEE单精度浮点数。
默认使用大端模式。

BinaryFormat.Single(Binary.FromText("41C80000", BinaryEncoding.Hex))

BinaryFormat.Text

BinaryFormat.Text(length as any, optional encoding as nullable number) as function

返回一个函数，函数使用length指定的字节数和指定的编码encoding将二进制转为文本。
参数length可以是整数或者返回整数的BinaryFormat.*函数，使用函数时将读取二进制值最前面的对应类型字节数的字节作为读取长度。函数不能被BinaryFormat.ByteOrder修饰，如果需要设置字节序，可以在BinaryFormat.Text外部使用，对整个二进制值的字节序进行确认。
参数encoding默认使用TextEncoding.Utf8。

BinaryFormat.Text(
    BinaryFormat.UnsignedInteger16, 
    TextEncoding.Unicode
)(#binary({0, 4, 65, 00, 66, 00, 67}))

BinaryFormat.ByteOrder(
    BinaryFormat.Text(BinaryFormat.UnsignedInteger16), 
    ByteOrder.LittleEndian
)(#binary({2, 0, 65, 66, 67, 68}))

BinaryFormat.ByteOrder(
    BinaryFormat.Text(BinaryFormat.UnsignedInteger16), 
    ByteOrder.BigEndian
)(#binary({0, 6, 0xe4, 0xbd, 0xa0, 0xe5, 0xa5, 0xbd}))

BinaryFormat.Text(
    BinaryFormat.UnsignedInteger16
)(#binary({0, 6, 0xe4, 0xbd, 0xa0, 0xe5, 0xa5, 0xbd}))

BinaryFormat.Transform

BinaryFormat.Transform(binaryFormat as function, function as function) as function

返回一个函数，该函数会对二进制值执行binaryFormat并将生成的结果作为参数传递给function并最终返回结果。
该函数不会将二进制值全部遍历，仅执行binaryFormat一次。

BinaryFormat.Transform(
    BinaryFormat.UnsignedInteger16, 
    (x) => x + 1
)(#binary({0, 1, 2, 3}))

BinaryFormat.UnsignedInteger16

BinaryFormat.UnsignedInteger16(binary as binary) as any

读取二进制值的前2个字节并将其转换为16位无符号整数。
默认使用大端模式。

BinaryFormat.UnsignedInteger16(#binary({128, 1}))

BinaryFormat.UnsignedInteger32

BinaryFormat.UnsignedInteger32(binary as binary) as any

读取二进制值的前4个字节并将其转换为32位有符号整数。
默认使用大端模式。

BinaryFormat.UnsignedInteger32(#binary({128, 0, 0, 1}))

BinaryFormat.UnsignedInteger64

BinaryFormat.UnsignedInteger64(binary as binary) as any

读取二进制值的前8个字节并将其转换为32位有符号整数。
默认使用大端模式。

BinaryFormat.UnsignedInteger64(#binary({128, 0, 0, 0, 0, 0, 0, 1}))