# 機能設計書 146-matches

## 概要

本ドキュメントは、Hack Standard Library (HSL) の `Regex\matches` 関数の機能設計を定義する。正規表現パターンで文字列をテストし、マッチするかどうかをboolで返す関数である。

### 本機能の処理概要

**業務上の目的・背景**：テキスト処理やバリデーションにおいて、文字列がパターンにマッチするかどうかを判定するだけで十分な場面が多い。本機能は、マッチの詳細を取得せずにマッチの有無のみを効率的に判定する手段を提供する。first_matchの結果がnullかどうかを確認するよりも意図が明確になる。

**機能の利用シーン**：フォームバリデーション（メールアドレス、電話番号の形式チェック）、ファイル名のフィルタリング、入力値の形式検証など、マッチの有無のみが重要な場面で利用される。

**主要な処理内容**：
1. 内部のregex_match関数を呼び出し
2. 結果がnullでないかをboolで返却

**関連システム・外部連携**：PCREライブラリに依存する正規表現エンジンを使用。

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

## 関連画面

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

## 機能種別

バリデーション / データ処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $haystack | string | Yes | 検索対象の文字列 | なし |
| $pattern | Pattern<Match> | Yes | PCRE正規表現パターン | PCREパターンとして有効であること |
| $offset | int | No | 検索開始位置（デフォルト: 0） | 文字列長の正負範囲内 |

### 入力データソース

関数呼び出し時の引数

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | bool | マッチする場合true、しない場合false |

### 出力先

関数の戻り値として返却

## 処理フロー

### 処理シーケンス

```
1. _Private\regex_matchを呼び出し
   └─ マッチング処理を実行
2. 結果がnullでないか判定
   └─ $match !== null
3. bool値を返却
   └─ true または false
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[regex_match を呼び出し]
    B --> C{マッチ結果 !== null?}
    C -->|Yes| D[true を返却]
    C -->|No| E[false を返却]
    D --> F[終了]
    E --> F
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-146-1 | マッチ判定 | マッチが存在する場合はtrue、存在しない場合はfalse | 常時 |
| BR-146-2 | オフセット考慮 | 指定されたオフセット以降でのマッチを判定 | offsetが指定された場合 |
| BR-146-3 | 部分一致 | 文字列全体でなく部分一致で判定 | 常時 |

### 計算ロジック

- マッチ判定: `_Private\regex_match($haystack, $pattern, inout $offset) !== null`

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

該当なし（データベース操作を行わない純粋関数）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | InvariantException | オフセットが範囲外 | オフセット値を修正 |
| PREG_* | Regex\Exception | PCREエラー | first_matchと同様 |

### リトライ仕様

該当なし

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

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

## パフォーマンス要件

- 時間計算量: O(n * m) - first_matchと同等
- 空間計算量: O(1) - マッチ結果を保持しない

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

- ReDoS（正規表現DoS）攻撃に注意
- `[]`: 純粋コンテキストで実行可能

## 備考

- マッチの詳細が必要な場合は`Regex\first_match()`を使用
- 全体一致を判定する場合はパターンに`^`と`$`を含める

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | regex.php | `src/regex/regex.php` | Pattern<Match>型（ジェネリックでないPattern）を確認 |

**読解のコツ**: matches関数は型パラメータを持たない。キャプチャグループの結果は不要なため、Pattern<Match>という基本型を使用。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | regex.php | `src/regex/regex.php` | matches関数の定義（81-87行目） |

**主要処理フロー**:
1. **81-85行目**: 関数シグネチャ - Pattern<Match>を受け取り、boolを返す
2. **86行目**: `_Private\regex_match(...) !== null` でマッチの有無を判定

#### Step 3: 実装の簡潔さを理解する

matches関数は非常にシンプルな実装:
```hack
function matches(
  string $haystack,
  Pattern<Match> $pattern,
  int $offset = 0,
)[]: bool {
  return _Private\regex_match($haystack, $pattern, inout $offset) !== null;
}
```

first_matchの結果がnullでないかを確認するだけの薄いラッパー。

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

```
Regex\matches($haystack, $pattern, $offset)
    |
    +-- _Private\regex_match($haystack, $pattern, inout $offset)
    |       └─ PCREマッチング
    |
    +-- 結果 !== null を判定
            └─ bool を返却
```

### データフロー図

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

$haystack ─────┐
               |
$pattern ──────┼──> _Private\regex_match ───> Match or null
               |           │
$offset ───────┘           v
                    !== null 判定 ───> bool ───> 戻り値
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| regex.php | `src/regex/regex.php` | ソース | matches関数の公開インターフェース |
| private.php | `src/regex/private.php` | ソース | regex_match内部実装 |
| RegexTest.php | `tests/regex/RegexTest.php` | テスト | matches関数のテストケース |
