# 機能設計書 124-ceil

## 概要

本ドキュメントは、Hack Standard Library (HSL) の `Math\ceil` 関数に関する機能設計書である。この関数は、数値の切り上げ（天井関数）を計算し、指定された値以上の最小の整数値をfloat型で返す。

### 本機能の処理概要

**業務上の目的・背景**：切り上げ演算は、ページネーション計算（総アイテム数からページ数を算出）、リソース割り当て（必要な最小コンテナ数の計算）、価格計算（端数の切り上げ）など、多くの業務処理で必要とされる基本的な数学演算である。`Math\ceil`関数は、PHPの`ceil`関数をラップし、Hackの型システムと統合された型安全な実装を提供する。

**機能の利用シーン**：ページネーションの総ページ数計算、配列を固定サイズに分割した場合のチャンク数計算、必要最小リソース数の算出、端数切り上げによる価格計算、ファイルサイズをブロックサイズで割った必要ブロック数計算など。

**主要な処理内容**：
1. 入力値（intまたはfloat）をPHPのceil関数に渡す
2. ceil関数が計算した結果（切り上げ値）をfloatとして返却

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

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

## 関連画面

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

## 機能種別

計算処理 / 数学関数

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $value | num | Yes | 切り上げ対象の数値（intまたはfloat） | なし |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | float | 切り上げられた値（$value以上の最小の整数値） |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. PHPのceil関数を呼び出し
   └─ \ceil($value) を実行
2. 結果をfloatとして返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[PHPのceil関数を呼び出し]
    B --> C[切り上げ値をfloatで返却]
    C --> D[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 切り上げ定義 | 戻り値は$value以上の最小の整数値である | 常に適用 |
| BR-002 | 整数入力 | 整数が入力された場合、同じ値がfloatとして返される | $valueがintの場合 |
| BR-003 | 負数の切り上げ | 負の数の切り上げは0に近い値となる（例: -3.5 → -3.0） | $value < 0の場合 |

### 計算ロジック

```
ceil(x) = ⌈x⌉ = 最小の整数 n where n >= x

例:
ceil(3.5) = 4.0
ceil(4.0) = 4.0
ceil(-3.5) = -3.0
ceil(-3.0) = -3.0
ceil(0.0) = 0.0
```

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

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

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

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

## パフォーマンス要件

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

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

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

## 備考

- 切り捨ての場合は `Math\floor()` を使用
- 四捨五入の場合は `Math\round()` を使用
- 整数除算の商（切り捨て）を取得する場合は `Math\int_div()` を使用
- capability context: `[]`（純粋関数）

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | compute.php | `src/math/compute.php` | num型の入力とfloat型の出力 |

**読解のコツ**: num型はintとfloatの両方を受け入れるユニオン型であり、ceil関数は常にfloatを返す。

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

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

**主要処理フロー**:
1. **91-96行目**: ドキュメントコメント - floor関数との対比を記載
2. **97行目**: 関数シグネチャ - `num $value`を受け取り`float`を返す
3. **98行目**: PHPのceil関数を呼び出して結果を返す

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

```
Math\ceil($value)
    │
    └─ \ceil($value)
```

### データフロー図

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

num型数値  ───▶  PHP\ceil()  ───▶  float型数値
(int/float)                        (切り上げ値)
```

### 関連ファイル一覧

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