# 機能設計書 63-between

## 概要

本ドキュメントは、dplyrパッケージの`between`関数の機能設計について記述する。`between`は値が指定された範囲内にあるかどうかを判定する関数である。

### 本機能の処理概要

`between`関数は、ベクトル`x`の各要素が`left`以上かつ`right`以下であるかを判定する。これは`x >= left & x <= right`の短縮形であり、SQLの`BETWEEN`演算子と同様の機能を提供する。

**業務上の目的・背景**：データ分析において、値が特定の範囲内にあるかどうかを判定する処理は非常に頻繁に行われる。日付範囲、数値範囲、カテゴリ範囲などのフィルタリングに使用される。`between`関数は、この一般的なパターンを簡潔に記述でき、可読性を向上させる。また、vctrsパッケージによる型安全な比較を提供し、順序付き因子などでも正しく動作する。

**機能の利用シーン**：
- 日付が特定の期間内にあるかを判定する場合
- 数値が特定の範囲内にあるかをフィルタリングする場合
- 順序付き因子で範囲判定を行う場合
- `filter()`内での範囲条件の指定

**主要な処理内容**：
1. `x`、`left`、`right`を共通の型にキャスト
2. `left`と`right`を`x`のサイズにリサイクル
3. `x`と`left`を比較して`x >= left`を判定
4. `x`と`right`を比較して`x <= right`を判定
5. 両方の条件を論理積（AND）で結合して返す

**関連システム・外部連携**：vctrsパッケージの`vec_cast_common`、`vec_recycle_common`、`vec_compare`関数に依存している。

**権限による制御**：特に権限による制御は行われない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 該当なし | - | 本プロジェクトはRライブラリであり、画面は存在しない |

## 機能種別

計算処理 / 比較演算 / バリデーション

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| x | vector | Yes | 判定対象のベクトル | 比較可能な型であること |
| left | vector | Yes | 範囲の下限値 | xと互換性のある型であること |
| right | vector | Yes | 範囲の上限値 | xと互換性のある型であること |
| ... | - | - | 未使用（空であること） | 空であること |
| ptype | vector | No | 出力型の指定（デフォルト: NULL） | 型指定またはNULL |

### 入力データソース

関数引数として直接渡されるベクトル

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| result | logical | 各要素が範囲内にあるかの論理ベクトル |

### 出力先

関数の戻り値として返却

## 処理フロー

### 処理シーケンス

```
1. 引数の検証
   └─ check_dots_empty0(...): 追加引数がないことを確認

2. 型の統一
   └─ vec_cast_common(x, left, right, .to = ptype): 共通の型にキャスト

3. サイズの調整
   └─ vec_recycle_common(left, right, .size = vec_size(x)): xのサイズにリサイクル

4. 下限との比較
   └─ vec_compare(x, left): xとleftを比較
   └─ left >= 0L: 0以上ならTRUE

5. 上限との比較
   └─ vec_compare(x, right): xとrightを比較
   └─ right <= 0L: 0以下ならTRUE

6. 結果の結合
   └─ left & right: 両方TRUEの場合のみTRUE
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[check_dots_empty0]
    B --> C[vec_cast_common]
    C --> D[vec_recycle_common]
    D --> E[vec_compare x, left]
    E --> F[left >= 0L]
    F --> G[vec_compare x, right]
    G --> H[right <= 0L]
    H --> I[left & right]
    I --> J[結果返却]
    J --> K[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-63-01 | 閉区間判定 | left <= x <= rightを判定（両端を含む） | 常時 |
| BR-63-02 | 型変換 | x, left, rightは共通の型に変換される | 常時 |
| BR-63-03 | リサイクル | left, rightはxのサイズにリサイクルされる | 常時 |
| BR-63-04 | 型指定 | ptypeで出力型を明示的に指定可能 | ptype指定時 |

### 計算ロジック

```
between(x, left, right) は以下と同等:
  x >= left & x <= right

順序付き因子の場合:
  ptype引数で型を指定することで、文字への変換を防ぐ
  例: between(x, "medium", "high", ptype = x)
```

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

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

該当なし（本関数はデータベース操作を行わない。ただし、dbplyrを通じてSQLに変換される場合がある）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 引数エラー | ...に引数が渡された場合 | ...に引数を渡さない |
| - | 型エラー | x, left, rightの型に互換性がない場合 | 互換性のある型に変換する |
| - | サイズエラー | リサイクルできないサイズの場合 | 適切なサイズに調整する |

### リトライ仕様

該当なし

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

該当なし（本関数はトランザクション処理を行わない）

## パフォーマンス要件

vctrsパッケージのベクトル演算を使用しており、大規模データでも効率的に動作する。

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

特になし

## 備考

- SQLの`BETWEEN`演算子に類似した機能を提供
- dbplyrを使用する場合、適切なSQLに変換される
- `join_by()`でもオーバーラップ結合用の`between()`ヘルパーが存在する（別機能）

---

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

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

### 推奨読解順序

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

本関数は入力ベクトルの型に依存するため、vctrsの型システムを理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | funs.R | `R/funs.R` | between関数定義（44-66行目） |

**読解のコツ**: `vec_cast_common`による型統一と`vec_compare`による比較操作の流れを追う。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | funs.R | `R/funs.R` | `between`関数本体（44-66行目） |

**主要処理フロー**:
1. **45行目**: `check_dots_empty0(...)` - 追加引数がないことを確認
2. **47行目**: 引数リストの作成
3. **50行目**: `vec_cast_common()` - 共通型へのキャスト
4. **55行目**: `vec_recycle_common()` - サイズのリサイクル
5. **59-60行目**: `vec_compare(x, left)` - 下限との比較
6. **62-63行目**: `vec_compare(x, right)` - 上限との比較
7. **65行目**: `left & right` - 最終結果の生成

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | funs.R | `R/funs.R` | ドキュメント（1-43行目） |

**主要ポイント**:
- **27-28行目**: 基本的な使用例
- **36-43行目**: 順序付き因子での`ptype`引数の使用例

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

```
between(x, left, right, ptype)
    │
    ├─ check_dots_empty0(...)      [vctrs]
    │
    ├─ vec_cast_common(...)        [vctrs]
    │      └─ 型の統一
    │
    ├─ vec_recycle_common(...)     [vctrs]
    │      └─ サイズの調整
    │
    ├─ vec_compare(x, left)        [vctrs]
    │      └─ 下限との比較
    │
    └─ vec_compare(x, right)       [vctrs]
           └─ 上限との比較
```

### データフロー図

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

    x ─────────────┐
                   │
 left ─────────────┼──▶ vec_cast_common ──▶ 型統一
                   │          │
right ─────────────┘          ▼
                       vec_recycle_common
                              │
                   ┌──────────┴──────────┐
                   ▼                     ▼
            vec_compare(x,left)   vec_compare(x,right)
                   │                     │
                   ▼                     ▼
               >= 0L                  <= 0L
                   │                     │
                   └──────────┬──────────┘
                              ▼
                           &（AND）
                              │
                              ▼
                        論理ベクトル
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| funs.R | `R/funs.R` | ソース | between関数および関連関数の実装 |
| filter.R | `R/filter.R` | ソース | betweenの典型的な使用先 |
