path: root/lab01/manual.md

# 实验 01：三元组程序使用手册

## 1. 程序简介

本程序使用 C++ 实现三元组（`Triplet`）数据类型，并将三元组视为三维向量进行基本运算。`Triplet` 使用模板实现，可以保存不同类型的元素；实验程序的标准输入测试部分使用 `Triplet<double>`。

程序支持三元组加法、三元组减法、标量乘法、三元组点积、求最大元素、判断非递减顺序以及判断非递增顺序。程序通过标准输入读取操作名称和数据，并将结果写入标准输出。程序本身不输出交互式提示信息，便于使用输入文件进行自动测试。

## 2. 文件说明

项目主要文件如下：

```text
.
├── main.cc
├── Triplet.hh
├── Makefile
├── 1.in
├── 1.out
├── 2.in
├── 2.out
└── ...
```

其中，`Triplet.hh` 保存三元组模板类的定义与实现；`main.cc` 是程序入口，负责读取输入、识别操作并输出结果；`Makefile` 提供编译和自动测试功能；`*.in` 为测试输入文件；`*.out` 为对应的期望输出文件。

## 3. 编译环境

推荐使用 GNU/Linux、Unix 类系统，或具有 GNU 工具链的 Windows 环境。编译器使用 GCC/G++，C++ 标准为 C++11，构建工具使用 GNU Make。

建议编译选项：

```text
-std=c++11 -Wall -Wextra -Wpedantic -O2
```

其中，`-std=c++11` 指定 C++11 标准；`-Wall -Wextra -Wpedantic` 启用常用编译警告；`-O2` 启用常规优化。

## 4. 编译程序

在项目目录执行：

```bash
make build
```

编译成功后生成可执行文件：

```text
triplet
```

也可以直接使用 `g++` 编译：

```bash
g++ -std=c++11 -Wall -Wextra -Wpedantic -O2 main.cc -o triplet
```

## 5. 运行方式

程序一次处理一个操作。输入的第一个字符串表示操作类型，后续数据格式由操作决定。

直接运行：

```bash
./triplet
```

也可以通过输入重定向运行：

```bash
./triplet < test01.in
```

## 6. 输入与输出格式

### 6.1 加法 `ADD`

输入两个三元组，计算对应分量之和。

```text
ADD
a1 a2 a3
b1 b2 b3
```

示例输入：

```text
ADD
1 2 3
4 5 6
```

输出：

```text
5 7 9
```

### 6.2 减法 `SUB`

输入两个三元组，计算第一个三元组减去第二个三元组。

```text
SUB
a1 a2 a3
b1 b2 b3
```

示例输入：

```text
SUB
10 8 6
1 2 3
```

输出：

```text
9 6 3
```

### 6.3 标量乘法 `SCALE`

输入一个三元组和一个标量，将三元组的每个分量乘以该标量。

```text
SCALE
a1 a2 a3
k
```

示例输入：

```text
SCALE
1 2 3
5
```

输出：

```text
5 10 15
```

### 6.4 点积 `DOT`

输入两个三元组，计算三维向量点积：

```text
a1*b1 + a2*b2 + a3*b3
```

输入格式：

```text
DOT
a1 a2 a3
b1 b2 b3
```

示例输入：

```text
DOT
1 2 3
4 5 6
```

输出：

```text
32
```

### 6.5 最大值 `MAX`

输入一个三元组，输出其中最大的元素。

```text
MAX
a1 a2 a3
```

示例输入：

```text
MAX
-5 12 7
```

输出：

```text
12
```

### 6.6 非递减判断 `ASC`

判断三元组是否满足：

```text
a1 <= a2 <= a3
```

输入格式：

```text
ASC
a1 a2 a3
```

示例输入：

```text
ASC
1 2 2
```

输出：

```text
true
```

若不满足条件，则输出：

```text
false
```

### 6.7 非递增判断 `DESC`

判断三元组是否满足：

```text
a1 >= a2 >= a3
```

输入格式：

```text
DESC
a1 a2 a3
```

示例输入：

```text
DESC
5 5 -1
```

输出：

```text
true
```

若不满足条件，则输出：

```text
false
```

## 7. 输入格式说明

程序使用 `std::cin` 读取数据，因此空格、换行和制表符都可以作为分隔符。以下两种输入形式等价：

```text
ADD
1 2 3
4 5 6
```

```text
ADD 1 2 3 4 5 6
```

为了便于阅读和整理测试用例，建议每个三元组单独占一行。

## 8. 自动测试

项目中的 `Makefile` 提供自动测试目标：

```bash
make test
```

执行后，`Makefile` 会自动扫描当前目录中的所有 `*.in` 文件。对于每个输入文件，例如 `1.in`，程序执行：

```bash
./triplet < 1.in
```

并将实际输出与对应的 `1.out` 进行比较。

测试通过时输出类似：

```text
[PASS] 1
```

测试失败时输出类似：

```text
[FAIL] 1
```

同时显示实际输出和期望输出之间的差异。全部测试完成后显示统计结果，例如：

```text
Passed: 10 / 10
```

## 9. 返回状态

程序正常完成操作时返回 `0`。标准输入中没有操作名称、输入数据数量不足、格式错误或操作名称不受支持时，程序返回非零状态。

对于未知操作，程序会向标准错误流输出错误信息并结束。例如：

```text
UNKNOWN
```

## 10. 注意事项

1. 操作名称区分大小写，应使用 `ADD`、`SUB`、`SCALE`、`DOT`、`MAX`、`ASC`、`DESC`。
2. 当前测试程序使用 `double` 作为三元组元素类型，因此整数和小数都可以输入。
3. `ASC` 和 `DESC` 使用非严格比较，因此相邻元素相等时仍可能返回 `true`。
4. 每次程序运行只处理一个操作。
5. 自动测试要求输入文件和输出文件使用相同的文件名前缀，例如 `test01.in` 对应 `test01.out`。