ucs_freq

统计完整文本行的出现次数与百分比，并按计数、字母或数值顺序输出

Release
UCS-1.1.0 · 2026-07-24
Input
一个或多个普通文本文件，或标准输入
Matching
默认整行精确、区分大小写
Output
COUNT (PERCENT%) TEXT
License
启动时检查 UCS license

1. Quick Start

# 文件中每一种完整行出现多少次
./ucs_freq timing_groups.txt

# 从 pipeline / stdin 读取
awk '{print $1}' timing.rpt | ./ucs_freq --sort count --order desc

# 合并多个输入文件后做一次全局统计
./ucs_freq run1.groups run2.groups run3.groups --trim --ignore_blank

没有 FILE 参数时从 stdin 读。传入多个文件时不是分别打印多个表，而是把全部行合并后统计一个总分布。

2. 统计规则

  1. 逐行读取输入并去掉行结束符。
  2. --trim 只去掉行首和行尾空白，不改变中间空格。
  3. --ignore_blank 在 trim 之后忽略空行；未启用时空行也是一个合法值。
  4. 其余每一个不同的完整行作为一个 key；匹配区分大小写。
  5. 百分比 = 该行次数 / 所有保留行数 × 100。
Input:
REG2REG
CLK2REG
REG2REG
 reg2reg

Command:
./ucs_freq --trim --ignore_blank input.txt

Result:
1 (25.00%) CLK2REG
1 (25.00%) reg2reg
2 (50.00%) REG2REG
精确行匹配：REG2REG 与 reg2reg 是两个值；A B 与 A B 也是两个值。需要字段级统计时，先用 awk/sed 抽取字段再通过 stdin 输入。

3. Command-Line Reference

Usage: ucs_freq [OPTIONS] [FILE]...

Options:
      --sort <count|alpha|numeric>  Sort key [default: count]
      --order <asc|desc>           Sort direction [default: asc]
      --ignore_blank               Ignore blank lines
      --trim                       Trim leading/trailing whitespace
  -h, --help
  -V, --version
Option行为适用场景
--sort count按出现次数排序；次数相同按文本稳定区分。找 dominant group、message 或 cell type。
--sort alpha按整行字典序。生成可比较、可 diff 的名称列表。
--sort numeric把整行解析为浮点数后排序。输入每行只有一个数值时使用。
--order asc/desc控制最终输出方向。count + desc 用于最高频优先。
--trim移除外侧空白。源文件缩进不一致但内容应归并。
--ignore_blank不统计空行。报告包含格式分隔空行。

numeric 只建议用于纯数值输入；混入非数值文本时不应依赖其相对顺序。

4. 使用案例

4.1 统计 timing path group

rg "^Path Group:" report_timing.rpt \
  | sed 's/^Path Group:[[:space:]]*//' \
  | ./ucs_freq --trim --ignore_blank --sort count --order desc

4.2 统计 ERROR 类别

rg -o "\\b(ERROR|WARN|FATAL)-[A-Z0-9_-]+" run.log \
  | ./ucs_freq --sort count --order desc

4.3 合并多个 stage 的 cell purpose

./ucs_freq create_db.purpose place_opt.purpose route_opt.purpose \
  --trim --ignore_blank --sort alpha --order asc

4.4 数值行排序

./ucs_freq --sort numeric --order asc slack_values.txt

5. Troubleshooting

现象原因与处理
同一个名称出现两行检查大小写、中间空格和不可见字符；先使用 --trim，需要进一步归一化时在 stdin pipeline 中处理。
空白值被统计增加 --ignore_blank；若空白行含空格，同时增加 --trim。
多个文件的百分比不像单文件多个文件会合并为一个总体，百分比分母是所有保留行总数。
压缩文件无法直接读该工具读取普通文本；使用 gzip -dc file.gz | ucs_freq ...。
License error确认 UCS license 有效；Linux 环境需要 OpenSSL。
验证：标准输入、单/多文件、trim、blank、三种排序和正反顺序均按 UCS-1.1.0 当前实现核对。