# 機能設計書 122-abs

## 概要

本ドキュメントは、Hack Standard Library (HSL) の `Math\abs` 関数に関する機能設計書である。この関数は、数値の絶対値を取得する。整数（int）と浮動小数点数（float）の両方に対応し、入力と同じ型で結果を返す。

### 本機能の処理概要

**業務上の目的・背景**：絶対値の計算は、距離計算、差分計算、数値の正規化など、多くの数学的処理で必要とされる基本的な演算である。`Math\abs`関数は、PHPの`abs`関数と同様の機能を提供しつつ、Hackの型システムと統合された型安全な実装を提供する。これにより、コンパイル時の型チェックが可能となり、より堅牢なコードを書くことができる。

**機能の利用シーン**：座標間の距離計算、数値の差の絶対値取得、負の数を正に変換する処理、数値の大きさ（magnitude）の取得、閾値判定での符号を無視した比較など、広範な数学的処理で使用される。

**主要な処理内容**：
1. 入力数値の符号を判定
2. 負の数の場合は符号を反転して正の数に変換
3. 正の数またはゼロの場合はそのまま返却
4. 入力と同じ型（intまたはfloat）で結果を返す

**関連システム・外部連携**：本機能はHSLライブラリ内部で完結し、外部システムとの連携はない。

**権限による制御**：本機能に権限による制御は存在しない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 本プロジェクト（Hack Standard Library）はUIを持たないライブラリのため該当なし |

## 機能種別

計算処理 / 数学関数

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $number | T as num | Yes | 絶対値を求める対象の数値（intまたはfloat） | なし（全ての数値を受け入れる） |

### 入力データソース

呼び出し元から直接渡される数値パラメータ。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | T | 入力数値の絶対値。入力がintならint、floatならfloatで返される |

### 出力先

戻り値として呼び出し元に返却。

## 処理フロー

### 処理シーケンス

```
1. 符号判定
   └─ $number < 0 かどうかを判定
2. 結果計算
   └─ 負の場合: -$number を返す
   └─ 正またはゼロの場合: $number をそのまま返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{$number < 0 ?}
    B -->|Yes| C[-$number を返す]
    B -->|No| D[$number を返す]
    C --> E[終了]
    D --> E
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 符号反転 | 負の数は符号を反転して正の数として返す | $number < 0 の場合 |
| BR-002 | 型保持 | 入力の型（int/float）と同じ型で結果を返す | 常に適用 |
| BR-003 | PHP_INT_MIN特殊ケース | PHP_INT_MINの絶対値はオーバーフローにより負の値を返す可能性がある | $number === PHP_INT_MIN の場合 |

### 計算ロジック

```
abs(x) = |x| = {
  -x  (x < 0 の場合)
   x  (x >= 0 の場合)
}
```

**特殊ケース**：`PHP_INT_MIN`（最小の表現可能な整数）の絶対値は、対応する正の数が整数としてオーバーフローするため、実装依存の結果となる。一般的には`abs(PHP_INT_MIN) === PHP_INT_MIN`となり、負の値を返す。整数が非負であることを保証するには `$v & PHP_INT_MAX` を使用することが推奨される。

## データベース操作仕様

### 操作別データベース影響一覧

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | - | 本関数はエラーをスローしない |

### リトライ仕様

リトライは不要。純粋な計算関数である。

## トランザクション仕様

本機能はトランザクション制御を行わない。

## パフォーマンス要件

- 時間計算量: O(1)
- 空間計算量: O(1)

## セキュリティ考慮事項

特になし。純粋な数学計算関数である。

## 備考

- ジェネリック型`T as num`を使用することで、入力と出力の型が一致することを型レベルで保証
- capability context: `[]`（純粋関数）
- PHP_INT_MINのオーバーフロー挙動はソースコードのコメントに記載されている

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

Hackのnum型（intとfloatのユニオン型）を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | compute.php | `src/math/compute.php` | num型の使用方法とジェネリック型パラメータ |

**読解のコツ**: `T as num`はジェネリック型制約で、Tがintまたはfloatのサブタイプであることを示す。これにより入力がintなら出力もint、入力がfloatなら出力もfloatとなる。

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | compute.php | `src/math/compute.php` | abs関数の定義（15-28行目） |

**主要処理フロー**:
1. **15-24行目**: ドキュメントコメント - PHP_INT_MINの特殊ケースについての警告
2. **25行目**: 関数シグネチャ - `T as num`ジェネリック制約
3. **27行目**: 三項演算子による符号判定と結果計算

### プログラム呼び出し階層図

```
Math\abs($number)
    │
    └─ 三項演算子: $number < 0 ? -$number : $number
```

### データフロー図

```
[入力]           [処理]              [出力]

num型数値  ───▶  符号判定  ───▶  num型数値（絶対値）
(int/float)      & 反転        (int/float)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| compute.php | `src/math/compute.php` | ソース | abs関数の実装 |
| MathComputeTest.php | `tests/math/MathComputeTest.php` | テスト | abs関数のユニットテスト |
