ランダムに配列のキーを選択する

# Random\Randomizer::pickArrayKeys

(PHP 8 >= 8.2.0)

Random\Randomizer::pickArrayKeys — ランダムに配列のキーを選択する

### 説明

public function Random\Randomizer::pickArrayKeys(array `$array`, int `$num`): array

指定された `array` に存在する、 `num` 個の異なる配列のキーを等確率に選びます。

指定された `array` の、 個々のキーが返される確率は等しくなります。

警告

配列のキーの選ばれ方は、 指定された `array` の内部構造に依存します。 ふたつの配列が等しく、かつ Random\Engine の内部的なステートが等しくても、 指定された配列の作られ方によっては返されるキーが異なる可能性があります。

### パラメータ

`array`

  キーを選ぶ配列

`num`

  返すべき配列のキーの数。 `1` 以上かつ、 `array` の要素数以下である必要があります。

### 戻り値

`array` の 異なる `num` 個のキーを含んだ配列を返します。

返される配列はリスト (array_is_list()) になります。 これは array_keys() が返す配列のサブセットです。

### エラー / 例外

- `num` の値が `1` より小さかったり、 `array` の要素数より大きい場合、 ValueError がスローされます。
- `Random\Randomizer::$engine` に存在する Random\Engine::generate() メソッド がスローした、あらゆる Throwable がスローされます。

### 例

例1 Random\Randomizer::pickArrayKeys() の例

    <?php
    $r = new \Random\Randomizer();

    $fruits = [ 'red' => '🍎', 'green' => '🥝', 'yellow' => '🍌', 'pink' => '🍑', 'purple' => '🍇' ];

    // 配列のキーをふたつ、ランダムに取り出します
    echo "Keys: ", implode(', ', $r->pickArrayKeys($fruits, 2)), "\n";

    // 別の配列のキーを3つ取り出します
    echo "Keys: ", implode(', ', $r->pickArrayKeys($fruits, 3)), "\n";
    ?>

上の例の出力は、 たとえば以下のようになります。

    Keys: yellow, purple
    Keys: red, green, yellow

例2 ランダムに値を取り出す

    <?php
    $r = new \Random\Randomizer();

    $fruits = [ 'red' => '🍎', 'green' => '🥝', 'yellow' => '🍌', 'pink' => '🍑', 'purple' => '🍇' ];

    $keys = $r->pickArrayKeys($fruits, 2);
    // 取り出したキーの値を検索します
    $selection = array_map(
        static fn ($key) => $fruits[$key],
        $keys
    );

    echo "Values: ", implode(', ', $selection), "\n";
    ?>

上の例の出力は、 たとえば以下のようになります。

    Values: 🍎, 🍇

### 参考

- array_keys() - 配列のキーすべて、あるいはその一部を返す

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