# API設計書

## 概要

本ドキュメントは、Hack Standard Library (HSL) のライブラリAPI設計書です。HSLはHack言語向けの標準ライブラリであり、vec、dict、keyset等のHack配列を操作するための関数群、文字列操作、数学関数、非同期処理、ファイル・ネットワークI/O等の機能を提供します。

**注意**: 本ライブラリはWeb APIではなく、プログラミング言語のライブラリAPIです。HTTPエンドポイントは存在しません。

## 共通仕様

### 名前空間

HSLの全ての関数は `HH\Lib` 名前空間配下に定義されています。

```hack
use namespace HH\Lib\{Vec, Dict, Keyset, Str, Math, C, Regex};
```

### 型パラメータ

多くの関数はジェネリクス（型パラメータ）を使用しています:
- `Tv`, `Tv1`, `Tv2`: 値の型
- `Tk`, `Tk1`, `Tk2`: キーの型
- `Ts`: スカラー型
- `T`: 汎用型パラメータ

### コンテキスト係数

関数の末尾に `[]`, `[ctx $predicate]`, `[leak_safe]` 等のコンテキスト係数が付与されている場合があります。

### 共通の引数パターン

| パターン | 説明 |
| --- | --- |
| `Traversable<Tv>` | 走査可能なコレクション |
| `KeyedTraversable<Tk, Tv>` | キー付き走査可能なコレクション |
| `Container<Tv>` | コンテナ型 |
| `(function(Tv)[_]: bool)` | 述語関数（フィルター用） |
| `(function(Tv)[_]: Ts)` | マッピング関数 |

## API一覧

| カテゴリ | 名前空間 | 説明 |
| --- | --- | --- |
| Vec | `HH\Lib\Vec` | vec配列操作関数群 |
| Dict | `HH\Lib\Dict` | dict配列操作関数群 |
| Keyset | `HH\Lib\Keyset` | keyset配列操作関数群 |
| C | `HH\Lib\C` | コンテナ問い合わせ関数群 |
| Str | `HH\Lib\Str` | 文字列操作関数群 |
| Math | `HH\Lib\Math` | 数学関数群 |
| Regex | `HH\Lib\Regex` | 正規表現関数群 |
| Random | `HH\Lib\{PseudoRandom, SecureRandom}` | 乱数生成関数群 |
| Async | `HH\Lib\Async` | 非同期処理サポート |
| File | `HH\Lib\File` | ファイルI/O |
| IO | `HH\Lib\IO` | 汎用I/O |
| TCP | `HH\Lib\TCP` | TCP通信 |

## 各APIエンドポイント定義

### Vec (vec配列操作)

#### 1. Vec\concat

複数のTraversableを連結して新しいvecを返します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function concat<Tv>(Traversable<Tv> $first, Container<Tv> ...$rest)[]: vec<Tv>` |
| 時間計算量 | O(n + m) |
| 空間計算量 | O(n + m) |

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| $first | Traversable<Tv> | ○ | 最初のTraversable |
| ...$rest | Container<Tv> | - | 追加のContainer群 |

**戻り値**

| 型 | 説明 |
| --- | --- |
| vec<Tv> | 連結された新しいvec |

---

#### 2. Vec\zip

2つのTraversableの要素をペアにした新しいvecを返します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function zip<Tv, Tu>(Traversable<Tv> $first, Traversable<Tu> $second)[]: vec<(Tv, Tu)>` |
| 時間計算量 | O(min(m, n)) |
| 空間計算量 | O(min(m, n)) |

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| $first | Traversable<Tv> | ○ | 1つ目のTraversable |
| $second | Traversable<Tu> | ○ | 2つ目のTraversable |

**戻り値**

| 型 | 説明 |
| --- | --- |
| vec<(Tv, Tu)> | タプルのvec（短い方の長さに合わせる） |

---

#### 3. Vec\diff

最初のTraversableの要素から、他のTraversableに含まれない要素のみを返します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function diff<Tv1 as arraykey, Tv2 as arraykey>(Traversable<Tv1> $first, Traversable<Tv2> $second, Container<Tv2> ...$rest)[]: vec<Tv1>` |
| 時間計算量 | O(n + m) |
| 空間計算量 | O(n + m) |

---

#### 4. Vec\filter

述語関数を満たす要素のみを含む新しいvecを返します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function filter<Tv>(Traversable<Tv> $traversable, ?(function(Tv)[_]: bool) $value_predicate = null)[ctx $value_predicate]: vec<Tv>` |
| 時間計算量 | O(n * p) |
| 空間計算量 | O(n) |

**パラメータ**

| パラメータ名 | 型 | 必須 | デフォルト | 説明 |
| --- | --- | --- | --- | --- |
| $traversable | Traversable<Tv> | ○ | - | 入力Traversable |
| $value_predicate | (function(Tv)[_]: bool) | - | boolvalキャスト | フィルター関数 |

---

#### 5. Vec\filter_nulls

null以外の要素のみを含む新しいvecを返します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function filter_nulls<Tv>(Traversable<?Tv> $traversable)[]: vec<Tv>` |
| 時間計算量 | O(n) |
| 空間計算量 | O(n) |

---

#### 6. Vec\map

各要素に関数を適用した結果の新しいvecを返します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function map<Tv1, Tv2>(Traversable<Tv1> $traversable, (function(Tv1)[_]: Tv2) $value_func)[ctx $value_func]: vec<Tv2>` |
| 時間計算量 | O(n) |
| 空間計算量 | O(n) |

---

#### 7. Vec\flatten

ネストされたTraversableを平坦化します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function flatten<Tv>(Traversable<Container<Tv>> $traversables)[]: vec<Tv>` |
| 時間計算量 | O(n) |
| 空間計算量 | O(n) |

---

#### 8. Vec\sort

ソートされた新しいvecを返します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function sort<Tv>(Traversable<Tv> $traversable, ?(function(Tv, Tv)[_]: num) $comparator = null)[ctx $comparator]: vec<Tv>` |
| 時間計算量 | O((n log n) * c) |
| 空間計算量 | O(n) |

---

#### 9. Vec\take

最初のn要素を含む新しいvecを返します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function take<Tv>(Traversable<Tv> $traversable, int $n)[]: vec<Tv>` |
| 時間計算量 | O(n) |
| 空間計算量 | O(n) |

---

#### 10. Vec\drop

最初のn要素を除いた新しいvecを返します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function drop<Tv>(Traversable<Tv> $traversable, int $n)[]: vec<Tv>` |
| 時間計算量 | O(n) |
| 空間計算量 | O(n) |

---

#### 11. Vec\unique

重複を除いた新しいvecを返します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function unique<Tv as arraykey>(Traversable<Tv> $traversable)[]: vec<Tv>` |
| 時間計算量 | O(n) |
| 空間計算量 | O(n) |

---

#### 12. Vec\reverse

逆順の新しいvecを返します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function reverse<Tv>(Traversable<Tv> $traversable)[]: vec<Tv>` |
| 時間計算量 | O(n) |
| 空間計算量 | O(n) |

---

#### 13. Vec\shuffle

ランダム順の新しいvecを返します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function shuffle<Tv>(Traversable<Tv> $traversable)[leak_safe]: vec<Tv>` |
| 時間計算量 | O(n) |
| 空間計算量 | O(n) |

---

### Dict (dict配列操作)

#### 1. Dict\map

各値に関数を適用した新しいdictを返します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function map<Tk as arraykey, Tv1, Tv2>(KeyedTraversable<Tk, Tv1> $traversable, (function(Tv1)[_]: Tv2) $value_func)[ctx $value_func]: dict<Tk, Tv2>` |
| 時間計算量 | O(n * f) |
| 空間計算量 | O(n) |

---

#### 2. Dict\from_keys

キーのリストと値生成関数から新しいdictを作成します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function from_keys<Tk as arraykey, Tv>(Traversable<Tk> $keys, (function(Tk)[_]: Tv) $value_func)[ctx $value_func]: dict<Tk, Tv>` |
| 時間計算量 | O(n * f) |
| 空間計算量 | O(n) |

---

#### 3. Dict\from_values

値のリストとキー生成関数から新しいdictを作成します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function from_values<Tk as arraykey, Tv>(Traversable<Tv> $values, (function(Tv)[_]: Tk) $key_func)[ctx $key_func]: dict<Tk, Tv>` |
| 時間計算量 | O(n) |
| 空間計算量 | O(n) |

---

#### 4. Dict\group_by

値をキー生成関数でグループ化します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function group_by<Tk as arraykey, Tv>(Traversable<Tv> $values, (function(Tv)[_]: ?Tk) $key_func)[ctx $key_func]: dict<Tk, vec<Tv>>` |
| 時間計算量 | O(n * f) |
| 空間計算量 | O(n) |

---

#### 5. Dict\flip

キーと値を入れ替えた新しいdictを返します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function flip<Tk, Tv as arraykey>(KeyedTraversable<Tk, Tv> $traversable)[]: dict<Tv, Tk>` |
| 時間計算量 | O(n) |
| 空間計算量 | O(n) |

---

### Str (文字列操作)

#### 1. Str\contains

文字列が部分文字列を含むか判定します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function contains(string $haystack, string $needle, int $offset = 0)[]: bool` |

---

#### 2. Str\search

部分文字列の最初の出現位置を返します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function search(string $haystack, string $needle, int $offset = 0)[]: ?int` |

---

#### 3. Str\replace

文字列の置換を行います。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function replace(string $haystack, string $needle, string $replacement)[]: string` |

---

#### 4. Str\capitalize

最初の文字を大文字にします。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function capitalize(string $string)[]: string` |

---

#### 5. Str\uppercase / Str\lowercase

大文字・小文字変換を行います。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function uppercase(string $string)[]: string` |
| シグネチャ | `function lowercase(string $string)[]: string` |

---

#### 6. Str\length

文字列のバイト長を返します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function length(string $string)[]: int` |
| 時間計算量 | O(1) |

---

#### 7. Str\starts_with / Str\ends_with

接頭辞・接尾辞の判定を行います。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function starts_with(string $string, string $prefix)[]: bool` |
| シグネチャ | `function ends_with(string $string, string $suffix)[]: bool` |

---

### C (コンテナ問い合わせ)

#### 1. C\count

コンテナの要素数を返します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function count(readonly Container<mixed> $container)[]: int` |
| 時間計算量 | O(1) |
| 空間計算量 | O(1) |

---

#### 2. C\contains

値がコンテナに含まれるか判定します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function contains<T1, T2>(readonly Traversable<T1> $traversable, readonly T2 $value)[]: bool` |
| 時間計算量 | O(n)（keysetとConstSetはO(1)） |

---

#### 3. C\contains_key

キーがコンテナに含まれるか判定します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function contains_key<Tk1 as arraykey, Tk2 as arraykey, Tv>(readonly KeyedContainer<Tk1, Tv> $container, readonly Tk2 $key)[]: bool` |
| 時間計算量 | O(1) |

---

#### 4. C\any

述語を満たす要素が存在するか判定します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function any<T>(Traversable<T> $traversable, ?(function(T)[_]: bool) $predicate = null)[ctx $predicate]: bool` |
| 時間計算量 | O(n) |

---

#### 5. C\every

全ての要素が述語を満たすか判定します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function every<T>(Traversable<T> $traversable, ?(function(T)[_]: bool) $predicate = null)[ctx $predicate]: bool` |
| 時間計算量 | O(n) |

---

### Math (数学関数)

#### 1. Math\abs

絶対値を返します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function abs<T as num>(T $number)[]: T` |

---

#### 2. Math\ceil / Math\floor

切り上げ・切り捨てを行います。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function ceil(num $value)[]: float` |
| シグネチャ | `function floor(num $value)[]: float` |

---

#### 3. Math\round

四捨五入を行います。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function round(num $val, int $precision = 0)[]: float` |

---

#### 4. Math\sqrt

平方根を返します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function sqrt(num $arg)[]: float` |

---

#### 5. Math\sin / Math\cos / Math\tan

三角関数を計算します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function sin(num $arg)[]: float` |
| シグネチャ | `function cos(num $arg)[]: float` |
| シグネチャ | `function tan(num $arg)[]: float` |

---

#### 6. Math\from_base / Math\to_base

基数変換を行います。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function from_base(string $number, int $from_base)[]: int` |
| シグネチャ | `function to_base(int $number, int $to_base)[]: string` |

---

### Regex (正規表現)

#### 1. Regex\first_match

最初のマッチを返します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function first_match<T as Match>(string $haystack, Pattern<T> $pattern, int $offset = 0)[]: ?T` |

---

#### 2. Regex\every_match

全てのマッチを返します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function every_match<T as Match>(string $haystack, Pattern<T> $pattern, int $offset = 0)[]: vec<T>` |

---

#### 3. Regex\matches

パターンにマッチするか判定します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function matches(string $haystack, Pattern<Match> $pattern, int $offset = 0)[]: bool` |

---

#### 4. Regex\replace

パターンマッチした部分を置換します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function replace(string $haystack, Pattern<Match> $pattern, string $replacement, int $offset = 0)[]: string` |

---

### Random (乱数生成)

#### 1. PseudoRandom\int

疑似乱数整数を生成します（暗号用途には不適切）。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function int(int $min = \PHP_INT_MIN, int $max = \PHP_INT_MAX)[leak_safe]: int` |

---

#### 2. PseudoRandom\float

疑似乱数浮動小数点数を生成します（範囲: [0.0, 1.0)）。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function float()[leak_safe]: float` |

---

### Async (非同期処理)

#### 1. Async\Semaphore

非同期処理の同時実行数を制限するセマフォ。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| クラス | `final class Semaphore<Tin, Tout>` |

**メソッド**

| メソッド | 説明 |
| --- | --- |
| `__construct(int $concurrentLimit, (function(Tin): Awaitable<Tout>) $f)` | コンストラクタ |
| `waitForAsync(Tin $value): Awaitable<Tout>` | 同時実行数を制限しながら処理を実行 |

---

### File (ファイルI/O)

#### 1. File\open_read_only

読み取り専用でファイルを開きます。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function open_read_only(string $path): CloseableReadHandle` |

---

#### 2. File\open_write_only

書き込み専用でファイルを開きます。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function open_write_only(string $path, WriteMode $mode = WriteMode::OPEN_OR_CREATE, int $create_file_permissions = 0644): CloseableWriteHandle` |

---

#### 3. File\open_read_write

読み書き可能でファイルを開きます。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function open_read_write(string $path, WriteMode $mode = WriteMode::OPEN_OR_CREATE, int $create_file_permissions = 0644): CloseableReadWriteHandle` |

---

### IO (入出力)

#### ReadHandle インターフェース

読み込み可能なハンドルのインターフェース。

**メソッド**

| メソッド | 説明 |
| --- | --- |
| `readImpl(?int $max_bytes = null): string` | 即座に読み込み（ブロックしない） |
| `readAllowPartialSuccessAsync(?int $max_bytes = null, ?int $timeout_ns = null): Awaitable<string>` | 非同期読み込み |
| `readAllAsync(?int $max_bytes = null, ?int $timeout_ns = null): Awaitable<string>` | 全データを非同期読み込み |
| `readFixedSizeAsync(int $size, ?int $timeout_ns = null): Awaitable<string>` | 固定サイズを非同期読み込み |

---

#### WriteHandle インターフェース

書き込み可能なハンドルのインターフェース。

**メソッド**

| メソッド | 説明 |
| --- | --- |
| `writeImpl(string $bytes): int` | 即座に書き込み（ブロックしない） |
| `writeAllowPartialSuccessAsync(string $bytes, ?int $timeout_ns = null): Awaitable<int>` | 非同期書き込み |
| `writeAllAsync(string $bytes, ?int $timeout_ns = null): Awaitable<void>` | 全データを非同期書き込み |

---

### TCP (TCP通信)

#### 1. TCP\connect_async

TCPソケットに非同期接続します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `async function connect_async(string $host, int $port, ConnectOptions $opts = shape()): Awaitable<CloseableSocket>` |

**パラメータ**

| パラメータ名 | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| $host | string | ○ | 接続先ホスト名またはIPアドレス |
| $port | int | ○ | 接続先ポート番号 |
| $opts | ConnectOptions | - | 接続オプション（IPバージョン、タイムアウト等） |

---

### Keyset (keyset操作)

#### 1. Keyset\diff

差集合を返します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function diff<Tv1 as arraykey, Tv2 as arraykey>(Traversable<Tv1> $first, Traversable<Tv2> $second, Container<Tv2> ...$rest)[]: keyset<Tv1>` |
| 時間計算量 | O(n + m) |
| 空間計算量 | O(n) |

---

#### 2. Keyset\intersect

積集合を返します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function intersect<Tv as arraykey>(Traversable<Tv> $first, Traversable<Tv> $second, Container<Tv> ...$rest)[]: keyset<Tv>` |
| 時間計算量 | O(n + m) |
| 空間計算量 | O(n) |

---

#### 3. Keyset\filter

述語を満たす要素のみを含む新しいkeysetを返します。

**基本情報**

| 項目 | 内容 |
| --- | --- |
| シグネチャ | `function filter<Tv as arraykey>(Traversable<Tv> $traversable, ?(function(Tv)[_]: bool) $value_predicate = null)[ctx $value_predicate]: keyset<Tv>` |
| 時間計算量 | O(n * p) |
| 空間計算量 | O(n) |

---

## 備考

1. **ライブラリの特徴**: HSLは純粋関数を中心に設計されており、副作用を最小限に抑えています。多くの関数は新しいコレクションを返し、元のコレクションを変更しません。

2. **非推奨関数**: `_nd` サフィックスの付いた関数（例: `open_read_only_nd`）は非推奨です。サフィックスなしのバージョンを使用してください。

3. **ロケール対応**: 文字列関数には `_l` サフィックスのロケール対応版が存在します（例: `Str\length_l`）。

4. **計算量**: 各関数のドキュメントに時間・空間計算量が記載されています。これはパフォーマンスチューニングの参考になります。

5. **型安全性**: HSLはHack言語の型システムを最大限活用しており、型チェッカーによる静的検証が可能です。
