值

Black2024年12月22日大约 13 分钟

值

值是通过表达式计算生成的数据。值都有类型，每种类型都有与之对应的语法、运算符（操作符）和内部关联的类型。

名称	类型	直面值
null	`null`	null
逻辑	`logical`	true、false
数字	`number`	1.2、1e5、-.5
时间	`time`	#time(09,15,23)
日期	`date`	#date(2022, 03, 05)
日期时间	`datetime`	#datetime(2022, 03, 05, 09, 15)
带时区的日期时间	`datetimezone`	#datetimezone(2022, 03, 05, 09, 15, 23, 08, 00)
持续时间	`duration`	#duration(1, 2, 15, 55)
文本	`text`	"hello"
二进制	`binary`	#binary("AQID")、#binary({0x65, 0x66})
列表	`list`	{1, 2, 3}
记录	`record`	[A = 1, B = 2]
表	`table`	#table({"A", "B"}, { {1, "X"}, {3, "Y"} })
函数	`function`	(x) => x + 1
类型	`type`	type number、type [A = number, B = text]

需要注意的是：并非所有的类型都有与之对应的值，比如：any和none。

逻辑

逻辑值用于布尔计算，只有两个值：true和false。

逻辑值是字面值，可以直接输入。

M严格区分类型，逻辑值不可以直接与数字进行数学运算。

支持运算：

比较运算
逻辑计算
??

逻辑值的原生类型是内部类型logical。

数字

数值（number value）用于数字和算术运算。

数字是字面值，可以直接输入。

.5 
.5e+6
2.3E-3
0xFFFF
0xffff

数字至少以双精度表示（可以保留更高的精度）。双精度表示形式与[IEEE 754-2008]中定义的二进制浮点运算的IEEE 64位双精度标准一致。双精度浮点数的动态范围约为5.0e324至1.7e308，精度15-16位。

特殊值：

正零和负零。通常与0用法相同，仅在某些特殊情况下不同。
正无穷（#infinity）和负无穷（-#infinity）。由非0除以0得到的。
非数值（Not-a-Number value）（#nan），通常写为NaN。由无效的数学运算产生，如：0 / 0。

二进制数学运算使用Precision执行。精度决定了操作数被舍入的域和操作的域。再没有明确指明精度的情况下，使用双精度执行此类操作（这里双精度指Precision.Double）。

如果数学运算的结果对于目标格式来说太小，则运算结果是正零或负零。
如果数学运算的结果对于目标格式来说太大，则运算结果是正无穷或负无穷。
如果数学运算无效，则运算结果为NaN。
如果浮点运算至少一个操作数是NaN，则结果是NaN。

支持运算：

四则运算
比较运算
??
前置+或-

数值的原生类型是内部类型number。

运算符	左操作数	右操作数	结果类型	含义
`x + y`或`y + x`	`time`	`duration`	`time`	对时间偏移一段时间
`x - y`	`time`	`duration`	`time`	同上，只是反向偏移
`x - y`	`time`	`time`	`duration`	时间之间的持续时间
`x & y`	`date`	`time`	`datetime`	合并为日期时间

运算符	左操作数	右操作数	结果类型	含义
`x + y`或`y + x`	`date`	`duration`	`date`	对日期偏移一段时间
`x - y`	`date`	`duration`	`date`	同上，只是反向偏移
`x - y`	`date`	`date`	`duration`	日期之间的持续时间
`x & y`	`date`	`time`	`datetime`	合并为日期时间

运算符	左操作数	右操作数	结果类型	含义
`x + y`或`y + x`	`datetime`	`duration`	`datetime`	对日期时间偏移一段时间
`x - y`	`datetime`	`duration`	`datetime`	同上，只是反向偏移
`x - y`	`datetime`	`datetime`	`duration`	日期时间之间的持续时间

带时区的日期时间

带时区的日期时间值包含日期时间和时区。

时区部分是指从UTC时间偏移的时间，偏移的时间只能是-14:00到14:00之间。除了附带时区信息，datetimezone和datetime行为和属性基本一致。

带时区的日期时间使用内置函数#datetimezone构建：

#datetimezone(
    year, month, day, 
    hour, minute, second, 
    offset-hours, offset-minutes
)

参数取值范围：

1 ≤ year ≤ 9999
1 ≤ month ≤ 12
1 ≤ day ≤ 31
0 ≤ hour ≤ 24
0 ≤ minute ≤ 59
0 ≤ second ≤ 59
-14 ≤ offset-hour ≤ 14
-59 ≤ offset-minute ≤ 59

second可以是小数，其他均为整数。

如果日期不存在，将会报错。

如果时间中的时设置为24时或者时间整体会舍入到24时（比如：23:59:59.99999999），将会报错。
offset-hour和offset-minute组合后的值必须介于-14:00:00和14:00:00之间（含两端）。

支持运算：

比较运算
??
其他运算，同time，见下表：

运算符	左操作数	右操作数	结果类型	含义
`x + y`或`y + x`	`datetimezone`	`duration`	`datetimezone`	对日期时间偏移一段时间（不考虑时区）
`x - y`	`datetimezone`	`duration`	`datetimezone`	同上，只是反向偏移
`x - y`	`datetimezone`	`datetimezone`	`duration`	日期时间之间的持续时间（会考虑时区）

注意事项：

与duration计算不会考虑时区。
相同类型相减，会考虑时区。
datetimezone值存储时会考虑时区，比如#datetimezone(1, 1, 1, 0, 0, 0, 1, 0)会报错。因为考虑时区信息，此时日期会越过可表示的日期范围。
转换函数可能会考虑时区，需谨慎。

警告

通常不需要带时区的日期时间，因为数据基本都在一个时区内。但如果数据跨时区或者执行环境跨时区，那将会导致本地时间不一致。

本地时间（local time）是指事物所在地的时间，不同地区可能会因为时区不同，导致同一时刻的时间不同。
比如：

北京时间（东八区、UTC+8）2022-05-01T12:00:00+8:00
协调世界时（UTC）2022-05-01T04:00:00+0:00
纽约时间（西五区）2022-04-30T23:00:00-5:00

如果服务器位于纽约，而你需要北京时间，此时如果不使用时区，那么你很可能得到纽约时间。此时需要使用UTC时间，然后设置到成东八区，得到转换后的本地的时间。

带时区的日期时间值的原生类型是内部类型datetimezone。

运算符	左操作数	右操作数	结果类型	含义
`x + y`或`y + x`	`T`	`duration`	`T`	对`T`偏移
`x + y`	`duration`	`duration`	`duration`	持续时间求和
`x - y`	`T`	`duration`	`T`	对`T`偏移
`x - y`	`T`	`T`	`duration`	两个`T`的时间差
`x - y`	`duration`	`duration`	`duration`	持续时间的差
`x * y`或`y * x`	`duration`	`number`	`duration`	持续时间的倍数
`x / y`	`duration`	`number`	`duration`	持续时间的分数

文本

文本值表示Unicode字符序列。

文本值是字面值，可以直接输入（有时可能需要使用转义序列）。

text-literal:
    "text-literal-characters_opt"
text-literal-characters:
    text-literal-character
    text-literal-characters_opt
text-literal-character:
    single-text-character
    character-escape-sequence
    double-quote-escape-sequence
single-text-character:
    Any character except " (U+0022) or # (U+0023) followed by ( (U+0028)
double-quote-escape-sequence:
    "" (U+0022, U+0022)

支持运算：

比较运算
&
??

文本值的原生类型是内部类型text。

二进制

二进制值表示字节序列。

二进制值可以使用内部函数#binary构建。

#binary({0x00, 0x01})
#binary("QUJD")

#binary可以使用的参数

字节列表。列表每个值介于0-255。
文本。使用BASE64编码的文本。

支持运算：

比较运算
??

二进制值的原生类型是内部类型binary。

列表

列表值是枚举时产生一系列值的值。列表中可以包含任意类型的值。

列表初始化语法：

list-expression:
    { item-list_opt }
item-list:
    item
    item , item-list
item:
    expression
    expression .. expression

初始化示例

{1, "A", error "error message"}

{1..10}

{1, 2..5, 6, 7, 8..11}

// 必须是单个Unicode字符
{"A".."H"}
{"你".."我"}

列表索引值以0开始。
列表可以包含无限个元素，如果对无限个元素的数组求元素个数，可能会报错或无法中止。
项在未访问之前不会计算。
虽然使用初始化语法构造的列表会根据item-list中的顺序生成项，但通常，从库函数返回的列表每次枚举时可能会生成不同的组合或不同数量的值。
比较两个列表是否相等时会考虑顺序

支持运算

&
=和<>
??

列表值的原生类型是内部类型list，即项类型为any的列表。

记录

记录是字段的有序序列，字段由字段名和字段值组成。字段名是在记录中定义字段的特殊文本值（标识符）。字段值可以是任何类型的值。

记录初始化语法：

record-expression:
    [ field-list_opt ]
field-list:
    field
    field , field-list
field:
    field-name = expression
field-name:
    generalized-identifier
    quoted-identifier

当评估记录表达式时：

分配给每个字段名的表达式用于确定关联字段的值（即等号右侧的表达式用于指定字段值）。
如果分配给字段名的表达式在计算时生成一个值，则该结果为记录的字段值。
如果分配给字段名的表达式在计算时引发错误，则引发错误的事实和引发的错误值一起记录在该字段中。对该字段的后续访问都会使用记录的错误值重新引发错误。
表达式在类似于父环境的环境中进行评估，使用记录中除了正在初始化的字段的每个字段名进行合并。
在相应字段访问之前，不会计算它在记录中的值。
记录中的值最多计算一次。
表达式的结果是一个包含空元数据记录的记录。
记录中的字段顺序由它们在初始化表达式中出现的顺序定义。
指定的每个字段名在记录中必须是唯一的，否则将引发错误。变量名使用序数比较（根据编码比较）。

其他事项

比较两个记录时，不考虑字段顺序。

支持运算：

=和<>
&
??

记录值的原生类型是内部类型record，即打开的空字段的记录。

表

表值是行的有序序列。行是值的有序序列。表的类型决定了表中所有行的长度、表列的名称、表列的类型以及表键（如果有）的结构。

表值可以使用内部函数#table构建。

#table({"A", "B"}, { {1, 2} })

#table(
    type table [A=number, B=text], 
    { {1, "X"}, {2, "Y"}, {3, "Z"} }
)

支持运算：

=和<>
&
??

比较两个表时会考虑行顺序，不考虑列顺序。

用&连接表时，如果有缺失值（比如两个表列名不完全同），将会填充null值。

表值的原生类型是自定义表类型（从内部类型table派生），即列类型为any，没有键。

type table[...]

函数

函数值是一种特殊的值，它可以被调用。

支持运算：

=和<>
??

函数等于本身，即使更换了类型依然相等。不同的函数即使定义一样也可能不相等。

函数值的原生类型是自定义函数类型（从内部类型function派生）。

类型

类型值是描述其他值类型的值。

支持运算：

=和<>
??