フォーマット文字列に基づき入力を処理する

# sscanf

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

sscanf — フォーマット文字列に基づき入力を処理する

### 説明

function sscanf(string `$string`, string `$format`, mixed `&...$vars`): array|int|null

関数 sscanf() は、printf() の入力版です。sscanf() は、文字列 `string` を読み込み、これを指定したフォーマット `format` に基づき解釈します。

フォーマット文字列の中のあらゆる空白文字は、入力文字列の中の 空白文字列にマッチします。つまり、フォーマット文字列の中にタブ文字 (`\t`) が含まれていても、 それは入力中の半角スペースにマッチしてしまうということです。

### パラメータ

`string`
  入力文字列。
`format`

  `string` を解釈するフォーマット。 sprintf() のドキュメントにある説明と比べて、以下の違いがあります。

  - ロケールに対応していません。
  - `F`、`g`、`G` および `b` はサポートしていません。
  - `D` は十進数値を表します。
  - `i` は基数検出つきの整数値を表します。
  - `n` は処理する文字数を表します。
  - `s` は、空白文字を読み取ると停止することを示します。
  - `argnum$` の代わりに `*` を指定すると、 この変換仕様に従った値の代入を抑制します。
`vars`
  オプションで指定する参照渡しの変数に、 パースされた値が格納されます。

### 戻り値

この関数のパラメータが二つだけの場合、処理された値は array として返されます。 それ以外の場合は、もしオプションのパラメータが渡されればこの関数は 割り当てられた値の数を返します。オプションのパラメータは 参照渡しにする必要があります。

`format` で期待する部分文字列のほうが 実際に `string` に存在するものより多い場合は `null` を返します。

オプションのパラメータを使用していて、 いずれかの値がパースされる前に入力文字列 `string` の終端に達した場合は、`-1` を返します。

### 例

例1 sscanf() の例

    <?php
    // シリアル番号を得る
    list($serial) = sscanf("SN/2350001", "SN/%d");
    // 続いて製造日を得る
    $mandate = "January 01 2000";
    list($month, $day, $year) = sscanf($mandate, "%s %d %d");
    echo "Item $serial was manufactured on: $year-" . substr($month, 0, 3) . "-$day\n";
    ?>

オプションのパラメータが指定された場合、この関数は、代入された値の数を返します。

例2 sscanf() - オプションパラメータの使用法

    <?php
    // author 情報を取得し、DocBook エントリを生成
    $auth = "24\tLewis Carroll";
    $n = sscanf($auth, "%d\t%s %s", $id, $first, $last);
    echo "<author id='$id'>
        <firstname>$first</firstname>
        <surname>$last</surname>
    </author>\n";
    ?>

### 参考

- printf() - フォーマット済みの文字列を出力する
- sprintf() - フォーマットされた文字列を返す
- fprintf() - フォーマットされた文字列をストリームに書き込む
- vprintf() - フォーマットされた文字列を出力する
- vsprintf() - フォーマットされた文字列を返す
- vfprintf() - フォーマットされた文字列をストリームに書き込む
- fscanf() - フォーマットに基づきファイルからの入力を処理する
- number_format() - 数字を千の位毎にグループ化してフォーマットする
- date() - Unixタイムスタンプを書式化する

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open