【PHP8.x】array_unshift()関数の使い方

Copy
1<?php
2
3/**
4 * PHPの array_unshift 関数が連想配列にどのように作用するかを示すサンプルコードです。
5 *
6 * array_unshift は配列の先頭に1つ以上の要素を追加し、追加後の配列の要素数を返します。
7 * 連想配列に適用された場合、既存の連想キーを持つ要素は後方に移動し、
8 * 新しく追加される要素には自動的に数値キー (0, 1, ...) が割り当てられます。
9 * これにより、連想配列の先頭に数値インデックスの要素が追加される形になります。
10 */
11function demonstrateArrayUnshiftWithAssociativeArray(): void
12{
13    // 元になる連想配列を定義します。
14    $myAssociativeArray = [
15        'id' => 101,
16        'name' => '商品A',
17        'price' => 5000
18    ];
19
20    echo "--- 適用前の連想配列 ---\n";
21    print_r($myAssociativeArray);
22    // 出力例:
23    // Array
24    // (
25    //     [id] => 101
26    //     [name] => 商品A
27    //     [price] => 5000
28    // )
29
30    // array_unshift 関数を使用して、配列の先頭に複数の要素を追加します。
31    // 最初の引数は変更される配列（参照渡し）、それ以降は追加する値です。
32    // 戻り値は、要素追加後の配列の新しい要素数です。
33    $newElementCount = array_unshift($myAssociativeArray, '在庫あり', true);
34
35    echo "\n--- array_unshift 適用後の連想配列 ---\n";
36    print_r($myAssociativeArray);
37    // 出力例:
38    // Array
39    // (
40    //     [0] => 在庫あり     // 新しく追加された要素には数値キーが割り当てられる
41    //     [1] => 1           // 新しく追加された要素には数値キーが割り当てられる (trueは1に変換)
42    //     [id] => 101        // 元の連想キーと値は維持され、後方に移動する
43    //     [name] => 商品A
44    //     [price] => 5000
45    // )
46
47    echo "配列の新しい要素数: " . $newElementCount . "\n";
48    // この例では、元の3要素に2要素が追加されたため、新しい要素数は 5 になります。
49}
50
51// 関数を実行します。
52demonstrateArrayUnshiftWithAssociativeArray();

PHP 8のarray_unshift関数は、指定された配列の先頭に1つ以上の要素を追加するための関数です。第一引数には変更したい配列を参照渡しで指定し、第二引数以降に追加したい値をいくつでも指定できます。この関数は、要素追加後の配列の新しい要素数を整数値で返します。

特に連想配列に対してarray_unshiftを適用した場合、追加される新しい要素には自動的に数値キー（0, 1, 2...）が割り当てられます。一方、もともと配列に含まれていた連想キーを持つ要素は、キーと値をそのまま保持しつつ、新しく追加された要素の後方に移動します。これにより、連想配列の先頭部分に数値インデックスの要素が挿入される形になります。

例えば、['id' => 101, 'name' => '商品A']という連想配列に'在庫あり'を追加すると、結果は[0 => '在庫あり', 'id' => 101, 'name' => '商品A']のようになります。元の連想キーは維持され、新しい数値キーが先頭に追加される点が特徴です。戻り値は、元の配列の要素数と追加した要素数を合計した、最終的な配列の要素数となります。

Copy
1<?php
2
3/**
4 * array_unshift の多次元配列での使用例を示します。
5 *
6 * この関数は、既存の多次元配列の先頭に新しい要素（この例では別の配列）を追加し、
7 * その結果と新しい配列の要素数を標準出力に表示します。
8 */
9function demonstrateArrayUnshiftWithMultidimensional(): void
10{
11    // 初期状態の多次元配列を定義します。
12    $products = [
13        ['id' => 101, 'item' => 'Product A', 'price' => 100],
14        ['id' => 202, 'item' => 'Product B', 'price' => 250],
15    ];
16
17    echo "--- 元の多次元配列 ---" . PHP_EOL;
18    print_r($products);
19    echo PHP_EOL;
20
21    // 配列の先頭に追加する新しい要素（別の配列）を定義します。
22    $newProduct = [
23        'id' => 303,
24        'item' => 'Product C',
25        'price' => 150
26    ];
27
28    echo "--- 追加する単一の要素 ---" . PHP_EOL;
29    print_r($newProduct);
30    echo PHP_EOL;
31
32    // array_unshift を使用して、多次元配列の先頭に新しい要素を追加します。
33    // array_unshift は最初の引数（&$array）を「参照渡し」で受け取るため、
34    // $products 配列自体が変更されます。
35    // 戻り値は、操作後の配列の新しい要素数（int型）です。
36    $newCount = array_unshift($products, $newProduct);
37
38    echo "--- array_unshift 実行後の多次元配列 ---" . PHP_EOL;
39    echo "追加後の配列の要素数: " . $newCount . PHP_EOL;
40    print_r($products);
41    echo PHP_EOL;
42
43    // 複数の要素を一度に追加する例
44    echo "--- 複数の要素を一度に追加する例 ---" . PHP_EOL;
45
46    $orders = [
47        ['order_id' => 1, 'customer' => 'Alice'],
48        ['order_id' => 2, 'customer' => 'Bob'],
49    ];
50
51    echo "元の配列:" . PHP_EOL;
52    print_r($orders);
53    echo PHP_EOL;
54
55    $newOrder1 = ['order_id' => 3, 'customer' => 'Charlie'];
56    $newOrder2 = ['order_id' => 4, 'customer' => 'David'];
57
58    echo "追加する複数の要素:" . PHP_EOL;
59    print_r($newOrder1);
60    print_r($newOrder2);
61    echo PHP_EOL;
62
63    // array_unshift は可変長引数（...$values）を受け取るため、複数の要素を一度に追加できます。
64    // 引数に指定された順序で配列の先頭に挿入されます。（$newOrder1 が一番先頭、次に $newOrder2）
65    $newCountMultiple = array_unshift($orders, $newOrder1, $newOrder2);
66
67    echo "array_unshift (複数の要素) 実行後の配列:" . PHP_EOL;
68    echo "追加後の配列の要素数: " . $newCountMultiple . PHP_EOL;
69    print_r($orders);
70    echo PHP_EOL;
71}
72
73// 関数を実行して、array_unshift の動作を確認します。
74demonstrateArrayUnshiftWithMultidimensional();

PHPのarray_unshift関数は、既存の配列の先頭に一つ以上の要素を追加する際に使用します。この関数は、最初の引数である$arrayを「参照渡し」で受け取るため、元の配列自体が直接変更されます。追加したい要素は$valuesとして複数指定することが可能で、引数に指定された順序で配列の先頭に挿入されます。関数は、操作後の配列の新しい要素数を整数（int）で返します。

このサンプルコードは、array_unshiftが多次元配列に対してどのように動作するかを示しています。最初に、商品情報を格納する多次元配列$productsを用意し、その先頭に新しい商品の配列$newProductを追加する例を紹介しています。array_unshiftの実行後には$products配列の先頭に$newProductが追加され、追加後の配列の要素数が表示されます。さらに、複数の注文情報を一度に配列の先頭へ追加する例も含まれており、$newOrder1、$newOrder2の順で$orders配列の先頭に挿入される様子が確認できます。これにより、既存の配列の先頭に効率的に要素を追加し、その結果を確認できることがわかります。

Copy
1<?php
2
3/**
4 * array_unshift のパフォーマンスを異なる配列サイズで計測する関数。
5 *
6 * array_unshift は、配列の先頭に要素を追加する際に、既存のすべての要素のインデックスを
7 * シフト（再割り当て）する必要があるため、配列のサイズが大きくなるにつれて
8 * 処理時間が増加する傾向があります。
9 * この関数は、そのパフォーマンス特性を示します。
10 */
11function measureArrayUnshiftPerformance(): void
12{
13    echo "Measuring array_unshift performance across different array sizes.\n";
14    echo "--------------------------------------------------------------\n";
15
16    // パフォーマンスをテストする配列サイズの一覧
17    $testSizes = [1000, 10000, 100000, 500000];
18
19    foreach ($testSizes as $size) {
20        // テスト用の配列を生成し、指定されたサイズになるまで要素を末尾に追加
21        // これにより、要素は連番のインデックスを持つことになります。
22        $array = [];
23        for ($i = 0; $i < $size; $i++) {
24            $array[] = $i;
25        }
26
27        // 配列の先頭に追加する値
28        $valueToAdd = 'new_element';
29
30        // array_unshift の実行時間を計測
31        $startTime = microtime(true);
32        array_unshift($array, $valueToAdd);
33        $endTime = microtime(true);
34
35        // 実行時間をミリ秒単位で計算
36        $duration = ($endTime - $startTime) * 1000;
37
38        // 結果を出力
39        printf("Array size: %7d, Time taken: %8.4f ms\n", $size, $duration);
40    }
41
42    echo "--------------------------------------------------------------\n";
43    echo "Observation: As the array size increases, the time taken by array_unshift generally increases.\n";
44    echo "This is because existing elements must be re-indexed to make space at the beginning of the array.\n";
45}
46
47// パフォーマンス計測関数を実行
48measureArrayUnshiftPerformance();
49
50?>

PHPのarray_unshift関数は、既存の配列の先頭に一つ以上の要素を追加する際に使用します。 第一引数には、要素を追加したい配列を参照渡しで指定します。これにより、元の配列自体が変更されます。 第二引数以降には、追加したい値をカンマ区切りで複数指定できます。これらの値は、指定された順序で配列の先頭に追加されます。 この関数は、要素が追加された後の配列の新しい要素数を整数で返します。

提供されたサンプルコードは、array_unshift関数のパフォーマンス特性を計測するものです。 コードでは、さまざまなサイズの配列を用意し、それぞれの配列の先頭に要素を追加する際の処理時間を測定しています。 この測定結果からわかるように、array_unshiftは配列の先頭に要素を追加するため、既存のすべての要素のインデックスを後ろにずらす（シフトする）必要があります。 そのため、配列のサイズが大きくなるほど、このシフト処理にかかる時間が増加し、パフォーマンスが低下する傾向があります。 大規模な配列に対して頻繁に先頭への追加を行う場合、このパフォーマンス特性を考慮した設計が重要となります。

Copy
1<?php
2
3/**
4 * array_unshift関数の動作を示すサンプルコードです。
5 *
6 * array_unshift関数は、指定された配列の先頭に一つまたは複数の要素を追加します。
7 * 追加された要素には数値キーが割り当てられ、既存の数値キーの要素は再インデックスされます。
8 * 既存の文字列キー（連想配列のキー）は変更されず保持されます。
9 * 関数は新しい配列の要素数を返します。
10 */
11
12// 最初に定義する連想配列
13$associativeArray = [
14    'fruit' => 'banana',
15    'color' => 'yellow',
16    'origin' => 'Ecuador',
17];
18
19echo "--- 初期状態の配列 ---\n";
20print_r($associativeArray);
21
22// array_unshiftを使って配列の先頭に新しい要素を追加します
23// この例では、連想配列に数値キーの要素が追加され、既存の連想キーはそのまま残ります。
24// array_unshiftは追加された要素に0からの数値キーを割り当てます。
25$newCount = array_unshift($associativeArray, 'apple', 'red');
26
27echo "\n--- array_unshift実行後の配列 ---\n";
28print_r($associativeArray);
29
30echo "新しい配列の要素数: " . $newCount . "\n";
31
32echo "\n--- 別の連想配列での挙動（数値キーが混在する場合） ---\n";
33$mixedArray = [
34    'first_item' => 'a',
35    0 => 'b', // 数値キー
36    'third_item' => 'c',
37    1 => 'd', // 数値キー
38];
39
40echo "--- 初期状態の混在配列 ---\n";
41print_r($mixedArray);
42
43// array_unshiftで要素を追加
44// 既存の文字列キー('first_item', 'third_item')は保持されます。
45// 既存の数値キー(0, 1)は再インデックスされ、新しい要素に0からの数値キーが割り当てられます。
46$newCountMixed = array_unshift($mixedArray, 'new_start_1', 'new_start_2');
47
48echo "\n--- array_unshift実行後の混在配列 ---\n";
49print_r($mixedArray);
50echo "新しい配列の要素数: " . $newCountMixed . "\n";
51
52?>

PHPのarray_unshift関数は、指定された配列の先頭に一つまたは複数の要素を追加する機能を提供します。最初の引数$arrayには操作対象の配列を渡します。この引数は参照渡しのため、関数が実行されると元の配列自体が直接変更されます。続く引数$valuesには、配列の先頭に追加したい要素を必要なだけ指定できます。関数は、要素追加後の配列の新しい要素数を整数値で返します。

この関数の重要な挙動として、追加される要素には0から始まる数値キーが割り当てられます。もし元の配列に数値キーの要素が含まれていた場合、それらは新しい要素の追加に伴い自動的に再インデックス（キーが振り直される）されます。特に連想配列の場合、既存の文字列キーを持つ要素はそのキーと値が変更されずに保持されます。これにより、連想配列の構造を保ちつつ、先頭に数値キーの新しい要素を追加できます。サンプルコードでは、連想配列の先頭に新たな要素が数値キーで追加され、元の連想キーが維持される挙動と、数値キーが混在する配列での再インデックスの様子が確認できます。