数学函数

概述

数学函数用于绝对值、取整、四舍五入、幂与对数、百分比和数字格式化。本篇共 9 个函数，全部在报表表达式、条件渲染、数据集计算字段（仅其中的 round、ceil、floor、abs、formatNumber，见 脚本使用说明）等所有 Sight Report 表达式环境中可用。

汇总类函数（sum、avg、max、min、count、rank）见 聚合与集合函数。

功能入口

• 单元格属性面板「数据」标签，内容类型为「公式」时的「内容公式」，点击「编辑」打开「表达式编辑」对话框。
• 对话框右侧「函数」标签页可搜索函数名并点击「插入」。
• 条件渲染的公式条件、新值公式，以及其他能输入表达式的位置同样可用。

函数列表

函数	作用	返回类型
abs	绝对值	BigDecimal
ceil	向上取整	Number
floor	向下取整	Number
round	四舍五入到指定小数位	Double
trunc	向零截断（不进位）	BigDecimal
pow	整数次幂	BigDecimal
log	以指定底数求对数	BigDecimal
percent	转为百分比文本	String
formatNumber	按格式模式格式化数字	String

函数详解

abs

语法

abs(number)

参数	类型	必填	说明
number	Number	是	要取绝对值的数值；传 null 返回 null

返回值：BigDecimal，与参数数值相同、符号为正；参数为 null 时返回 null。

示例

abs(-3.5)

结果：3.5

说明

• 整数、小数、BigDecimal 均可传入，内部统一转换为 BigDecimal。

ceil

语法

ceil(number)

参数	类型	必填	说明
number	Number	是	要向上取整的数值；传 null 返回 null

返回值：Number。参数为 Double/Float 时返回 Double；参数为 BigDecimal 时返回小数位为 0 的 BigDecimal；参数为整数类型时原样返回。

示例

ceil(2.1)

结果：3.0

ceil(7)

结果：7

说明

• 数据集中的数值列通常是 BigDecimal。对 BigDecimal，ceil 使用「远离零」的进位方式：正数向上取整（2.10 得 3），负数会向更小的方向取整（-1.20 得 -2），与数学上的向上取整不同；负数需要真正向上取整时请改用 trunc。

floor

语法

floor(number)

参数	类型	必填	说明
number	Number	是	要向下取整的数值；传 null 返回 null

返回值：Number。参数为 Double/Float 时返回 Double；参数为 BigDecimal 时返回小数位为 0 的 BigDecimal；参数为整数类型时原样返回。

示例

floor(2.9)

结果：2.0

floor(-2.1)

结果：-3.0

说明

• 对 Double/Float 参数，实现内部先转为 float 再取整，数值超过约一千六百万时精度不足；大数请使用 BigDecimal（数据集数值列）。

round

语法

round(number)
round(number, len)

参数	类型	必填	说明
number	Number	是	要四舍五入的数值；传 null 返回 null
len	int	否	保留的小数位数，省略时为 0

返回值：Double。

示例

round(3.1415, 2)

结果：3.14

round(2.5)

结果：3.0

round(-2.5)

结果：-3.0

说明

• 舍入规则为 HALF_UP（五入，负数按绝对值五入）。
• 实现按数值的十进制文本转换后舍入，因此 round(2.345, 2) 得到 2.35，不会受二进制浮点误差影响。
• 返回类型是 Double，整数结果也带小数点（如 3.0）。需要固定小数位显示时请使用 formatNumber 或单元格的数值格式。

trunc

语法

trunc(number)
trunc(number, len)

参数	类型	必填	说明
number	Number	是	要截断的数值；传 null 返回 null
len	int	否	保留的小数位数，省略时为 0（去掉全部小数）

返回值：BigDecimal。

示例

trunc(3.789)

结果：3

trunc(-3.789, 2)

结果：-3.78

说明

• 向零截断：直接丢弃多余小数位，不做任何进位，正负数都朝零方向。

pow

语法

pow(number, n)

参数	类型	必填	说明
number	Number	是	底数；传 null 返回 null
n	int	是	指数，必须是整数

返回值：BigDecimal，精确的整数次幂。

示例

pow(2, 10)

结果：1024

pow(1.5, 2)

结果：2.25

说明

• 基于 BigDecimal 的整数次幂，指数为负数或超出范围时会报错；不支持小数指数（即不能用它开方）。

log

语法

log(number, base)

参数	类型	必填	说明
number	Number	是	真数；任一参数为 null 返回 null
base	Number	是	底数

返回值：BigDecimal。

示例

log(100, 10)

结果：2.0

说明

• 实现为 Math.log(number) / Math.log(base) 的双精度计算再转换为 BigDecimal，结果可能带浮点尾数（例如 1000 以 10 为底得到 2.9999999999999996），需要整数结果时请配合 round。
• 真数或底数不合法（如小于等于 0）时计算结果不是有限数，转换时会报错。
• 两个参数都必须提供，没有省略底数的写法。
• 与脚本 import log 得到的日志模块是两回事：log(x, base) 是函数调用，log.info(...) 是日志对象。

percent

语法

percent(number)
percent(number, len)

参数	类型	必填	说明
number	Number	是	小数形式的比例，如 0.1234 表示 12.34%；传 null 返回 null
len	int	否	百分数保留的小数位数，省略时为 0

返回值：String，末尾带 %。

示例

percent(0.1234, 2)

结果："12.34%"

percent(0.5)

结果："50%"

说明

• 输入乘以 100 后按 HALF_UP 舍入到指定位数。
• 返回值是文本，不能再直接参与数值比较或运算；需要保留数值时请用单元格的百分比数值格式。

formatNumber

语法

formatNumber(value, pattern)

参数	类型	必填	说明
value	Object	是	要格式化的数值，也可以是可解析为数字的文本
pattern	String	是	Java DecimalFormat 格式模式，如 #,##0.00、0.0%、000

返回值：String。

示例

formatNumber(1234567.891, '#,##0.00')

结果："1,234,567.89"

formatNumber(0.256, '0.0%')

结果："25.6%"

formatNumber(5, '000')

结果："005"

说明

• value 或 pattern 为 null 时返回 null；value 为空字符串时返回空字符串；value 是无法解析的文本时原样返回该文本。
• pattern 为空字符串会报错「数字格式化的格式不能为空！」。
• 舍入使用 DecimalFormat 默认的 HALF_EVEN（银行家舍入）：formatNumber(2.5, '0') 得 "2"，formatNumber(3.5, '0') 得 "4"。需要「四舍五入」时先用 round 处理。
• 内部按 double 格式化，超过 15 位有效数字的大数值会有精度损失。

注意事项

注意：round 返回 Double、formatNumber 与 percent 返回文本。把它们的结果继续参与四则运算前，请确认类型：文本参与 -、*、/、% 时会按数值解析，但参与 + 时可能变成字符串拼接，详见 报表基本语法。

提示：数值列在数据集中通常是 BigDecimal；表达式里直接写的小数字面量（如 2.5）是 Double。两者在 ceil、floor、round 上的返回类型不同，这是上表「返回类型」列区分描述的原因。

相关文档

• 函数参考
• 聚合与集合函数
• 文本函数
• 报表基本语法
• 表达式与函数