第 24 章 脚本编制参考(四) 类Total

 Total 类
Total 类是作为聚集函数的容器提供的。Total 类包含许多用于进行聚集的函数。这些函数是 BIRT 对 JavaScript 的扩展，它们对一组行进行汇总。BIRT 报告引擎在下列两个阶段实现了函数：

在报告的数据转换阶段发生的聚集阶段
在生成和表示阶段发生的聚集访问阶段
BIRT 重新编写了任何包含聚集的脚本，从而创建了执行这两个阶段的已修订脚本。您只有在调试包含聚集函数的表达式时，了解此过程才十分重要。请研究在组的组脚中显示值的示例，其中，该值是在所有帐户的总计中所占的百分比。以下语句执行此操作：

(balance / Total.sum( balance, Total.OVERALL ) ) * 100.0

在以上示例中，Total.OVERALL 导致 BIRT 对所有行计算求和聚集函数，即使此表达式出现在组总计中亦如此。为了计算上一示例中的表达式，BIRT 将执行一次遍历以计算总计，然后执行第二次遍历以计算每个帐户的值。

Total 类的一般规则是：

聚集函数忽略空值。
应用程序可以有选择地指定分组级别。
应用程序可以有选择地指定条件。
应用程序不能创建此类的实例。
关于分组和过滤
所有聚集函数都允许使用两个可选参数来指示过滤和分组：

Total.<聚集函数> ( ..., filter, group )

关于过滤器参数
过滤器参数提供了一个布尔表达式，对于每一行，BIRT 都会对该表达式进行求值。在计算聚集时，BIRT 仅考虑与该过滤器匹配的行。例如，报告可以对活动客户的贷记限额进行求和，以确定最大贷记风险。

此表达式是在数据转换阶段执行的。它可以访问行中的列、参数、用户定义的函数以及上述上下文描述中定义的其他资源。例如：

Total.sum( row["CreditLimit"], row["Active"] == 'Y' );

指定过滤器参数 null、未定义过滤器参数或者指定 Total.NO_FILTER，都表示未提供过滤器。如果应用程序未提供过滤器，则过滤器缺省为未定义。如果提供了组参数，则必须提供 null 或 Total.NO_FILTER 以指示不进行过滤。

关于组参数
报告经常需要显示当前分组级别的总计。例如，假定一个报告按客户和订单进行分组，并且详细信息记录表示订单中的行项。每个行项都有单位价格和数量，如以下聚集函数所示：

Total.sum( row["price"] * row["quantity"] )

此聚集函数对当前组的金额进行求和。如果将此聚集放在订单组脚中，则它将显示该订单的行项之和。如果将其放在客户组脚中，它就会显示该客户的所有订单的所有行项之和。并且，如果将其放在报告组脚中，它就会显示所有客户的所有行项之和。

但是，应用程序有时需要访问另一分组级别的总计。例如，您可能想了解一个订单的总金额在该客户所有订单中所占的百分比。在这种情况下，必须访问除当前组以外的组的总计。可以使用分组参数来实现此目的：

Total.sum( row.CreditLimit, null, "Customer" );

组参数可以是下列其中一项：

Null，这表示当前分组级别。
当前分组级别或更高分组级别的组的名称。此名称是报告设计中指定的名称。
当前分组级别或更高分组级别的组的组键表达式。
组级别的数字索引。0 表示整体总计，1 表示最高级别的组，依此类推。
相对组索引：-1 表示比此组高一级的组，-2 表示比此组高两级的组，依此类推。
特殊名称“Overall”，此名称引用数据集的整体总计。也可以使用静态属性 Total.OVERALL。
下列示例演示了三类组参数：

Total.sum( row["myCol"] null, null ); // 当前组
Total.sum( row["myCol"], null, "Customer" ); // 按名称
Total.sum( row["myCol"], null, "row[`custID']" ); // 按组键
Total.sum( row["myCol"], null, 1 ); // 按组索引
Total.sum( row["myCol"], null, "Overall" ); // 整体总计
Total.sum( row["myCol"], null, 0 ); // 整体总计

使用分组参数时，必须提供过滤器参数。如果不需要过滤器，请指定 null 作为过滤器值。不能将组索引括在引号中，它必须是数字。即，1 表示级别为 1 的组，而 "1" 表示名为 "1" 的组。

静态属性
OVERALL

这是用于组参数的常量，它请求计算数据集的整体总计。
函数
ave( expr [, filter [, group ]] )
一组值的算术平均值。
count( [ filter [, group ]] )
行数。
countDistinct( expr [, filter [, group ]] )
相异值数。
first( expr [, filter [, group ]] )
序列中的第一个值。
isBottomN(expr, n, [, filter [, group ]] )
这个布尔值指示某个值是否是最小的 n 个值中的一个。
isBottomNPercent( expr, percentage, [, filter [, group ]] )
这个布尔值指示某个值是否是占 n% 的最小值中的一个。
isTopN(expr, n, [, filter [, group ]] )
这个布尔值指示某个值是否是最大 n 个中的一个。
isTopNPercent( expr, percentage, [, filter [, group ]] )
这个布尔值指示某个值是否是占 n% 的最大值中的一个。
last( expr [, filter [, group ]] )
序列中的最后一个值。
max( expr [, filter [, group ]] )
数字、字符串或日期序列的最大值。
median( expr [, filter [, group ]] )
数字序列的算术中值。
min( expr [, filter [, group ]] )
数字、字符串或日期序列的最小值。
mode( expr [, filter [, group ]] )
值序列的算术众数。
movingAve( expr, window [, filter [, group ]] )
数字序列的移动平均值，用户可以在其中指定计算平均值时要考虑的值的数目。
percentile( expr, percentage [, filter [, group ]] )
一组值的百分点值。
percentileRank( expr [, filter [, group ]])
某个值在数据集中的百分比排名。
percentSum( expr [, filter [, group ]])
在总计中所占的百分比。
quartile( expr, quartile,[ filter [, group ]])
一组值的四分点值。
rank( expr, ascending, [, filter [, group ]])
值的排名。
runningCount( [, filter [, group ]]
项数。
runningSum( expr [, filter [, group ]] )
与 sum 类似，但提供报告中给定点的移动总计。
stdDev( expr [, filter [, group ]] )
数字序列的算术标准方差。
sum( expr [, filter [, group ]] )
数字序列的和。
variance( expr [, filter [, group ]] )
数字序列的算术方差。
weightedAve( expr, weight [, filter [, group ]] )
数字序列的加权平均值。
Total.ave
此聚集函数计算算术平均值。如果表达式求值为数字，则此函数返回那些数字的平均值。如果表达式求值为日期，则此函数返回平均日期。

语法
Total.ave( expr [, filter [, group ]] )

参数
expr
要计算平均值的表达式。此表达式应该至少引用一个数据行列。数据类型可以是数字或日期。
filter
可选的过滤条件。
group
可选的组标识。
返回
此函数返回给定表达式的平均值。如果没有可用的行，则返回 null。

示例
以下语句返回班级中学生的平均年龄：

Total.ave( row.Age )

要返回班级中学生的平均生日，请使用以下语句：

Total.ave( row.BirthDate )

另请参阅
Total.median 聚集函数

Total.mode 聚集函数

Total.movingAve 聚集函数

Total.stdDev 聚集函数

Total.variance 聚集函数

Total.weightedAve 聚集函数

Total.count
此函数计算某个组中的行数。

语法
Total.count( [ filter [, group ]] )

参数
filter
可选的过滤条件。
group
可选的组标识。
返回
给定组中的匹配行数。如果没有可用的行，则返回零。
示例
此示例计算班级中的男女生数。需要创建两个数据项。请将第一个数据项设置为：

Total.sum( row.sex == 'M' );

将第二个数据项设置为：

Total.sum( row.sex == 'F' );

另请参阅
Total.countDistinct 聚集函数

Total.sum 聚集函数

Total.countDistinct
此函数计算某个组或数据集中的相异值数。expr 参数提供用于对值进行分组的表达式。此表达式引用一个数据行列。空值计作一个相异值。

语法
Total.countDistinct ( expr [, filter [, group ]] )

参数
expr
此表达式标识唯一的值。此表达式应该至少引用一个数据行列。数据类型可以是数字、字符串或日期。
filter
可选的过滤条件。
group
可选的组标识。
返回
组或数据集中的相异值数。如果没有可用的行，则返回零。

示例
假定我们要了解一组学生所代表的不同国家或地区的数目。我们可以定义一个使用以下表达式的数据项：

Total.countDistinct( row.Country )

在此语句中，row.Country 是一个列，它包含学生的祖国的名称或代码。假定某些行包含空值（这表示我们不知道该学生的祖国）。使用以下语句来指定不对这些行进行计数：

Total.countDistinct( row.Country, row.Country != null )

另请参阅
Total.count 聚集函数

Total.first
此聚集函数返回数据集中的第一个值。这就是使用为表或列表定义的排序顺序来访存行时在数据集中访存的第一个值。

语法
Total.first( expr [, filter [, group ]] )

参数
expr
要进行求值的表达式。此表达式应该至少引用一个数据行列。数据类型可以是数字、日期或字符串。
filter
可选的过滤条件。
group
可选的组标识。
返回
此函数返回行序列中的第一个值，或者如果数据集未包含任何行，则返回 null。

示例
假定一个报告列示了给定的一支股票在一段时间内的交易情况。以下语句将显示该股票的最早一次买入交易：

Total.first( row.TransDate, row.Action == 'Buy' );

另请参阅
Total.isBottomNPercent 聚集函数

Total.max 聚集函数

Total.min 聚集函数

Total.isBottomN
此函数返回一个布尔值，它指示所指定数字字段的值是否是最小的 n 个值中的一个。

语法
Total.isBottomN( expr, n, [, filter [, group ]] )

参数
expr
要进行求值的表达式。此表达式应该至少引用一个数据行列。数据类型只能是数字。
n
要测试的值的数目。
filter
可选的过滤条件。
group
可选的组标识。
返回
此函数返回 true 或 false。如果该数字字段的值是此列所有值中最小的 n 个值中的一个，则此函数返回 true。

示例
假定某个报告列有 5 行，它们分别包含值 1、2、3、4 和 5。Total.isBottomN(expr, 2) 将测试由 expr 表示的字段是否包含 1 或 2，即此列中最小的两个数字。

另请参阅
Total.isBottomNPercent

Total.isTopN

Total.isTopNPercent

Total.isBottomNPercent
此函数返回一个布尔值，它指示所指定数字字段的值是否是该列所有值中占 n% 的最小值中的一个。

语法
Total.isBottomNPercent( expr, n, [, filter [, group ]] )

参数
expr
要进行求值的表达式。此表达式应该至少引用一个数据行列。数据类型只能是数字。
n
要测试的值的百分比。
filter
可选的过滤条件。
group
可选的组标识。
返回
此函数返回 true 或 false。如果该字段的值是此列所有值中占 n% 的最小值中的一个，则此函数返回 true。

示例
假定某个报告列有 5 行，它们分别包含值 1、2、3、4 和 5。Total.isBottomNPercent(expr, 60) 将测试由 expr 表示的字段是否包含 1、2 或 3，即此列中占 60% 的最小数字。

另请参阅
Total.isBottomN

Total.isTopN

Total.isTopNPercent

Total.isTopN
此函数返回一个布尔值，它指示所指定数字字段的值是否是最大的 n 个值中的一个。

语法
Total.isTopN( expr, n, [, filter [, group ]] )

参数
expr
要进行求值的表达式。此表达式应该至少引用一个数据行列。数据类型只能是数字。
n
要测试的值的数目。
filter
可选的过滤条件。
group
可选的组标识。
返回
此函数返回 true 或 false。如果该数字字段的值是此列所有值中最大的 n 个值中的一个，则此函数返回 true。

示例
假定某个报告列有 5 行，它们分别包含值 1、2、3、4 和 5。Total.isTopN(expr, 2) 将测试由 expr 表示的字段是否包含 4 或 5，即此列中最大的两个数字。

另请参阅
Total.isTopNPercent

Total.isBottomN

Total.isBottomNPercent

Total.isTopNPercent
此函数返回一个布尔值，它指示所指定数字字段的值是否是该列所有值中占 n% 的最大值中的一个。

语法
Total.isTopNPercent( expr, n, [, filter [, group ]] )

参数
expr
要进行求值的表达式。此表达式应该至少引用一个数据行列。数据类型只能是数字。
n
要测试的值的百分比。
filter
可选的过滤条件。
group
可选的组标识。
返回
此函数返回 true 或 false。如果该字段的值是此列所有值中占 n% 的最大值中的一个，则此函数返回 true。

示例
假定某个报告列有 5 行，它们分别包含值 1、2、3、4 和 5。Total.isTopNPercent(expr, 60) 将测试由 expr 表示的字段是否包含 3、4 或 5，即此列中占 60% 的最大数字。

另请参阅
Total.isTopN

Total.isBottomN

Total.isBottomNPercent

Total.last
此函数返回数据集中的最后一个值。这就是使用为表或列表定义的排序顺序来访存行时在数据集中访存的最后一个值。

语法
Total.last( expr [, filter [, group ]] )

参数
expr
要进行求值的表达式。此表达式应该至少引用一个数据行列。数据类型可以是数字、日期或字符串。
filter
可选的过滤条件。
group
可选的组标识。
返回
此函数返回行序列中的最后一个值，如果数据集未包含任何行，则返回 null。

示例
假定一个报告列示了给定的一支股票在一段时间内的交易情况。以下语句将显示该股票的最近一次卖出交易：

Total.last( row.TransDate, row.Action == 'Sell' );

另请参阅
Total.first 聚集函数

Total.max 聚集函数

Total.min 聚集函数

Total.max
此函数计算给定表达式的最大值。将针对每一行来对此表达式进行求值，然后返回最大值。此函数可用于处理数字、日期或字符串。

语法
Total.max( expr [, filter [, group ]] )

参数
expr
要计算最大值的表达式。此表达式应该至少引用一个数据行列。数据类型可以是数字、字符串或日期。
filter
可选的过滤条件。
group
可选的组标识。
返回
此函数返回给定表达式的最大值。如果没有可用的行，它将返回 null。

示例
以下语句查找班级中年龄最大的学生：

Total.max( row.Age )

另请参阅
Total.first 聚集函数

Total.isBottomNPercent 聚集函数

Total.min 聚集函数

Total.median
此聚集函数计算算术中值。一半的值大于中值，另一半的值小于中值。

语法
Total.median( expr [, filter [, group ]] )

参数
expr
要计算平均值的表达式。此表达式应该至少引用一个数据行列。数据类型可以是数字或日期。
filter
可选的过滤条件。
group
可选的组标识。
返回
此函数返回给定表达式的中值。如果没有可用的行，则返回 null。

示例
以下语句返回班级中学生的年龄中值：

Total.median( row.Age )

并且，要返回班级中学生的生日中值，请使用以下语句：

Total.median( row.BirthDate )

另请参阅
Total.ave 聚集函数

Total.mode 聚集函数

Total.movingAve 聚集函数

Total.stdDev 聚集函数

Total.variance 聚集函数

Total.weightedAve 聚集函数

Total.min
此聚集函数计算给定表达式的最小值。将针对每一行来对此表达式进行求值，然后返回最小值。此函数可用于处理任何简单类型：数字、日期或字符串。

语法
Total.min( expr [, filter [, group ]] )

参数
expr
要计算最小值的表达式。此表达式应该至少引用一个数据行列。数据类型可以是数字、字符串或日期。
filter
可选的过滤条件。
group
可选的组标识。
返回
此函数返回给定表达式的最小值。如果没有可用的行，则返回 null。

示例
以下语句返回班级中年龄最小的学生的年龄：

Total.min( row.Age )

另请参阅
Total.first 聚集函数

Total.isBottomNPercent 聚集函数

Total.max 聚集函数

Total.mode
此聚集函数计算算术众数值。众数是数据中最频繁出现的值。例如，在序列 {1, 2, 3, 2, 4, 7} 中，由于 2 出现了两次，而其他数字只出现一次，所以众数为 2。如果数据集有多个众数，例如序列 {1,2,3,2,3} 的情况，mode 聚集函数将返回 null。

语法
Total.mode( expr [, filter [, group ]] )

参数
expr
要查找众数的表达式。此表达式应该至少引用一个数据行列。数据类型可以是数字、日期或字符串。
filter
可选的过滤条件。
group
可选的组标识。
返回
此函数返回给定表达式的众数值。如果没有可用的行，或者如果数据包含多个众数，则返回 null。

示例
以下语句返回班级中学生的最普遍年龄：

Total.mode( row.Age )

另请参阅
Total.ave 聚集函数

Total.median 聚集函数

Total.movingAve 聚集函数

Total.stdDev 聚集函数

Total.variance 聚集函数

Total.weightedAve 聚集函数

Total.movingAve
此聚集函数计算移动平均值。expr 参数指定要计算平均值的值，window 参数指定要考虑的行数。将按照上下文确定的顺序对各行计算平均值，此顺序通常由列表或表元素的排序顺序指定。

语法
Total.movingAve( expr, window [, filter [, group ]] )

参数
expr
要计算平均值的表达式。此表达式应该至少引用一个数据行列。结果必须是数字。
window
计算聚集时要考虑的行数。必须求值为数字。将在聚集启动时求值一次。
filter
可选的过滤条件。
group
可选的组标识。
返回
此函数返回给定表达式的移动平均值。如果没有可用的行，则返回 null。

示例
假定一个报告列示某个股票的每日报价。要显示该股票在最近 5 天的移动平均价，请使用以下语句：

Total.movingAve( row.price, 5 );

另请参阅
Total.ave 聚集函数

Total.median 聚集函数

Total.mode 聚集函数

Total.stdDev 聚集函数

Total.variance 聚集函数

Total.weightedAve 聚集函数

Total.percentile
此函数对一组值进行检查，并返回所有那些值中在所指定百分点处的值。例如，在一次测验后，您可能想了解所有分数的第 90 个百分点处的分数。

语法
percentile(expr, percentage [, filter [, group ]] )
参数
expr
此表达式应该指定要分析的值所在的数据行列。
percentage
0 与 1 之间的百分比值。
filter
可选的过滤条件。
group
可选的组标识。
返回
此函数返回所分析的一组值中指定百分点处的值。

示例
以下语句返回第 50 个百分点处的分数值：

Total.percentile( row.TestScore, 0.5)

如果所指定列中的一组测验分数是 10、20、30、40 和 50，则此语句将返回 30。

另请参阅
Total.percentRank

Total.percentSum

Total.quartile

Total.percentRank
此函数计算某个值在所指定字段中的百分比排名。

语法
percentRank( expr, filter [, group ]] )

参数
expr
此表达式应该至少引用一个数据行列。
filter
可选的过滤条件。
group
可选的组标识。
返回
此函数返回某个值在所指定字段中的百分比排名。返回值的范围是 0 到 1。

示例
以下语句返回一个分数在某个列中所有分数之间的百分比排名：

Total.percentRank( row.Scores )

如果求值范围中的分数是 10、10、20 和 50，并且包含此语句的单元格中的分数是 30，则返回值是 .5，这是因为半数的值大于 20，另一半的值小于 20。

另请参阅
Total.percentile

Total.percentSum

Total.quartile

Total.percentSum
此函数计算此值在范围内所有值之和中所占的百分比。

语法
percentSum( expr [, filter [, group ]] )

参数
expr
此表达式应该至少引用一个数据行列。
filter
可选的过滤条件。
group
可选的组标识。
返回
此函数返回此值在范围内所有值之和中所占的百分比。

示例
以下语句返回此订单金额在所有订单金额之和中所占的百分比：

Total.percentSum( row.OrderAmt )

另请参阅
Total.percentile

Total.percentRank

Total.quartile

Total.quartile
此函数计算所定义的一组值中的一个值，对于该值，该组中有 0%、25%、50%、75% 或 100% 的值大于该值。

语法
quartile( expr, quartile, [, filter [, group ]] )

参数
expr
此表达式描述一组要进行求值的值。它应该至少引用一个数据行列。
quartile
要返回的值的四分点。quartile 参数可以是 0、1、2、3 或 4，它们分别表示该组中的最小值、第一个四分点、第二个四分点、第三个四分点和最大值。
filter
可选的过滤条件。
group
可选的组标识。
返回
此函数返回所指定组中位于所指定四分点位置处的值。

示例
以下语句返回一个订单金额，75% 的订单金额小于该金额，25% 的订单金额大于该金额。

Total.quartile( row.OrderAmt, 3)

另请参阅
Total.percentile

Total.percentRank

Total.percentSum

Total.rank
此函数计算某个值在一组值中的排名。排名值的范围是 1 到该组中的值数目。如果两个值相等，则它们具有相同的排名。

语法
rank( expr [, filter [, group ]] )

参数
expr
此表达式标识一组要进行求值的数字。此表达式应该至少引用一个数据行列。这一组值可以是数字值、字符串值或日期值。
filter
可选的过滤条件。
group
可选的组标识。
返回
此函数返回一个整数来反映值的排名，其范围是 1 到该组值中的项数。

示例
以下语句返回 OrderAmt 字段在 OrderAmt 列中所有订单金额中的排名。

Total.rank( row.OrderAmt )

另请参阅
Total.percentRank

Total.runningCount
此函数计算动态行数。

语法
runningCount( filter [, group ]] )

参数
filter
可选的过滤条件。
group
可选的组标识。
返回
此函数返回动态行数。

示例
以下语句返回报告的动态行数：

Total.runningCount( )

另请参阅
Total.count 聚集函数

Total.percentRank 聚集函数

Total.stdDev
此聚集函数计算数字序列的统计标准方差。标准方差是对一组值的分布情况的度量。

语法
Total.stdDev( expr [, filter [, group ]] )

参数
expr
要分析的表达式。此表达式应该至少引用一个数据行列。结果必须是数字。
filter
可选的过滤条件。
group
可选的组标识。
返回
此函数返回给定表达式的标准方差。如果没有可用的行，则返回 null。

另请参阅
Total.ave 聚集函数

Total.median 聚集函数

Total.mode 聚集函数

Total.movingAve 聚集函数

Total.variance 聚集函数

Total.weightedAve 聚集函数

Total.sum
此聚集函数计算一个组中每一行的值的累加和。每一行的值都是使用 expr 参数中给定的表达式计算而得的。累加和是通过将所有这些值累加到一起获得的。

语法
Total.sum( expr [, filter [, group ]] )

参数
expr
要进行求和的表达式。此表达式应该至少引用一个数据行列。结果必须是数字。
filter
可选的过滤条件。
group
可选的组标识。
返回
给定表达式之和。如果没有可用的行，则返回零。

示例
以下语句计算某个客户的订单金额总计：

Total.sum( row.OrderAmt )

另请参阅
Total.count 聚集函数

Total.percentRank 聚集函数

Total.variance
此聚集函数计算数字序列的统计方差。方差是对一组值的分布情况的度量。

语法
Total.variance( expr [, filter [, group ]] )

参数
expr
要分析的表达式。此表达式应该至少引用一个数据行列。结果必须是数字。
filter
可选的过滤条件。
group
可选的组标识。
返回
此函数返回给定表达式的方差。如果没有可用的行，则返回 null。

另请参阅
Total.ave 聚集函数

Total.median 聚集函数

Total.mode 聚集函数

Total.movingAve 聚集函数

Total.stdDev 聚集函数

Total.weightedAve 聚集函数

Total.weightedAve
此聚集函数计算算术加权平均值。如果 expr 或 weight 参数求值为 null，则不对该行计算平均值。

语法
Total.weightedAve( expr, weight [, filter [, group ]] )

参数
expr
要计算平均值的表达式。此表达式应该至少引用一个数据行列。结果必须是数字。
weight
此表达式指定每一行的权重。结果必须是数字。
filter
可选的过滤条件。
group
可选的组标识。
返回
此函数返回给定表达式的加权平均值。如果没有可用的行，则返回 null。

示例
假定一个金融应用程序要对不同时间分批买入的给定股票进行跟踪。每个批次都有不同的买入价，并且许多股数都是按该价位买入的。以下语句计算加权平均买入价：

Total.weightedAve( row.purchasePrice, row.shareCount )

另请参阅
Total.ave 聚集函数

Total.median 聚集函数

Total.mode 聚集函数

Total.movingAve 聚集函数

Total.stdDev 聚集函数

Total.variance 聚集函数