# 機能設計書 53-trim_right

## 概要

本ドキュメントは、Hack Standard Library (HSL) の `Str\trim_right` 関数の機能設計書である。この関数は文字列の右端（末尾）から空白文字を除去する機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：
データ処理において、文字列の末尾にのみ余分な空白が含まれているケースがある。例えば、固定長フィールドのデータベースから取得した文字列や、ユーザーがコピー＆ペーストした際に末尾に残る空白など。`Str\trim_right` 関数は、先頭のインデントや意図的なプレフィックスを保持しながら、末尾の不要な文字だけを除去することを可能にする。

**機能の利用シーン**：
- 固定長フィールドの右側パディング除去
- ユーザー入力の末尾空白クリーニング
- ファイルパスやURLの末尾空白除去
- コードエディタでの行末空白除去
- レポート出力時の整形

**主要な処理内容**：
1. 入力文字列を受け取る
2. 文字マスクが指定されていない場合、デフォルトの空白文字セット（スペース、タブ、改行、キャリッジリターン、NULバイト、垂直タブ）を使用
3. 文字列の末尾から、マスクに含まれる文字を連続して除去
4. 処理済みの文字列を返却

**関連システム・外部連携**：
内部実装では `_Private\_Str\trim_right_l` を呼び出し、PHPネイティブの `rtrim()` 関数相当の処理を行う。ロケール対応版として `Str\trim_right_l()` も提供されている。

**権限による制御**：
本機能は純粋関数であり、権限による制御は存在しない。

## 関連画面

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

## 機能種別

文字列変換処理 / データクリーニング

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $string | string | Yes | 処理対象の文字列 | 任意の文字列を受け付ける |
| $char_mask | ?string | No | 除去対象の文字を指定するマスク（デフォルト: null） | nullの場合はデフォルトの空白文字セットを使用 |

### 入力データソース

関数呼び出し時の引数として直接渡される。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | string | 右端から空白文字（またはマスク文字）を除去した文字列 |

### 出力先

関数の戻り値として呼び出し元に返却される。

## 処理フロー

### 処理シーケンス

```
1. 関数呼び出し
   └─ Str\trim_right($string, $char_mask) が呼び出される
2. 内部関数への委譲
   └─ _Str\trim_right_l($string, $char_mask) を呼び出し
3. マスク判定
   └─ $char_mask が null の場合、デフォルトの空白文字セットを適用
4. 文字列処理
   └─ PHPのrtrim()関数相当の処理で右端の文字を除去
5. 結果返却
   └─ 処理済み文字列を返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[入力: $string, $char_mask]
    B --> C{$char_mask は null?}
    C -->|Yes| D[デフォルト空白文字セット適用]
    C -->|No| E[指定されたマスクを使用]
    D --> F[文字列右端からマスク文字を除去]
    E --> F
    F --> G[結果文字列を返却]
    G --> H[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-53-01 | デフォルト空白文字 | char_maskがnullの場合、スペース・タブ・改行・キャリッジリターン・NULバイト・垂直タブを除去 | $char_mask が null の場合 |
| BR-53-02 | カスタムマスク | 指定された文字マスクに含まれる文字のみを除去 | $char_mask が指定された場合 |
| BR-53-03 | 右端のみ処理 | 文字列の右端（末尾）のみから処理を行い、左端は変更しない | 常時 |

### 計算ロジック

特定の計算ロジックは存在しない。文字列操作のみ。

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

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

本機能はデータベース操作を行わない純粋関数である。

## エラー処理

### エラーケース一覧

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

### リトライ仕様

リトライは不要（同期的な純粋関数のため）

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

該当なし（データベース操作を行わないため）

## パフォーマンス要件

- 計算量: O(n) - n は入力文字列の長さ
- 純粋関数 `[]` として定義されており、副作用なし
- メモリ効率: 新しい文字列を生成して返却

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

- 入力文字列の末尾空白除去によるデータ正規化
- NULバイトの除去によりセキュリティリスクを軽減

## 備考

- 両端の除去には `Str\trim()` を使用
- 左端のみの除去には `Str\trim_left()` を使用
- 特定のサフィックス（固定文字列）の除去には `Str\strip_suffix()` を使用
- ロケール対応が必要な場合は `Str\trim_right_l()` を使用

---

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

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

### 推奨読解順序

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

本関数はプリミティブ型のみを扱うため、特別なデータ構造は存在しない。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | select.php | `src/str/select.php` | 関数シグネチャと引数の型を確認 |

**読解のコツ**: Hackの `?string` 型は null 許容の string 型を意味する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | select.php | `src/str/select.php` | trim_right 関数の実装（93-95行目） |

**主要処理フロー**:
1. **93行目**: `function trim_right(string $string, ?string $char_mask = null)[]: string` - 関数定義
2. **94行目**: `return _Str\trim_right_l($string, $char_mask);` - 内部実装への委譲

#### Step 3: ドキュメントコメントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | select.php | `src/str/select.php` | trim_right のドキュメント（82-92行目） |

**主要ポイント**:
- **83行目**: 右端から空白を除去する説明
- **87-89行目**: 関連関数へのリファレンス（trim, trim_left, strip_suffix）

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

```
Str\trim_right($string, $char_mask)
    │
    └─ _Str\trim_right_l($string, $char_mask)
           │
           └─ PHP rtrim() 相当の処理
```

### データフロー図

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

$string ────────────▶ Str\trim_right ────────▶ right-trimmed string
$char_mask ─────────▶     │
                          │
                          ▼
                    _Str\trim_right_l
                          │
                          ▼
                    PHP rtrim処理
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| select.php | `src/str/select.php` | ソース | trim_right関数のパブリックインターフェース |
| select_l.php | `src/str/select_l.php` | ソース | ロケール対応版のtrim_right実装 |
| StrSelectTest.php | `tests/str/StrSelectTest.php` | テスト | trim_right関数のユニットテスト |
