Array Functions

Array Functions

array

Name

array — Create an array

Description

array array(...);

Returns an array of the parameters. The parameters can be given an index with the => operator.

Note that array really is a language construct used to represent literal arrays, and not a regular function.

The following example demonstrates how to create a two-dimensional array, how to specify keys for associative arrays, and how to skip-and-continue numeric indices in normal arrays.

Example 1. array example

$fruits = array(

"fruits" => array("a"=>"orange","b"=>"banana","c"=>"apple"), "numbers" => array(1, 2, 3, 4, 5, 6)

"holes" => array("first", 5 => "second", "third")

);

array_walk

Name

array_walk — Apply a function to every member of an array.

Description

int array_walk(array arr, string func);

Applies the function named by func to each element of arr. The elements are passed as the first argument of func; if func requires more than one argument, a warning will be generated each time array_walk calls func. These warnings may be suppressed by prepending the '@' sign to the array_walk call, or by using error_reporting.

Note that func will actually be working with the elements of arr, so any changes made to those elements will actually be made in the array itself.

Example 1. array_walk example

$fruits = array("d"=>"lemon","a"=>"orange","b"=>"banana","c"=>"apple");

function test_alter( $item1 ) {

$item1 = 'bogus';

}

function test_print( $item2 ) { echo "$item2<br>\n";

}

array_walk( $fruits, 'test_print' ); array_walk( $fruits, 'test_alter' ); array_walk( $fruits, 'test_print' );

arsort

Name

arsort — Sort an array in reverse order and maintain index association

Description

void arsort(array array);

This function sorts an array such that array indices maintain their correlation with the array elements they are associated with. This is used mainly when sorting associative arrays where the actual element order is significant.

Example 1. arsort example

$fruits = array("d"=>"lemon","a"=>"orange","b"=>"banana","c"=>"apple"); arsort($fruits);

for(reset($fruits); $key = key($fruits); next($fruits)) { echo "fruits[$key] = ".$fruits[$key]."\n";

}

This example would display: fruits[a] = orange fruits[d] = lemon fruits[b] = banana fruits[c] = apple The fruits have been sorted in reverse alphabetical order, and the index associated with each element has been maintained.

See also: asort, rsort, ksort, and sort.

asort

Name

asort — Sort an array and maintain index association

Description

void asort(array array);

Example 1. asort example

$fruits = array("d"=>"lemon","a"=>"orange","b"=>"banana","c"=>"apple"); asort($fruits);

for(reset($fruits); $key = key($fruits); next($fruits)) { echo "fruits[$key] = ".$fruits[$key]."\n";

count

}

This example would display: fruits[c] = apple fruits[b] = banana fruits[d] = lemon fruits[a] = orange The fruits have been sorted in alphabetical order, and the index associated with each element has been maintained.

See also arsort, rsort, ksort, and sort.

Name

count — count elements in a variable

Description

int count(mixed var);

Returns the number of elements in var, which is typically an array (since anything else will have one element).

Returns 0 if the variable is not set. Returns 1 if the variable is not an array. See also: sizeof, isset, and is_array.

current

Name

current — return the current element in an array

Description

mixed current(array array);

each

Each array variable has an internal pointer that points to one of its elements. In addition, all of the elements in the array are linked by a bidirectional linked list for traversing purposes. The internal pointer points to the first element that was inserted to the array until you run one of the functions that modify that pointer on that array.

The current function simply returns the array element that's currently being pointed by the internal pointer. It does not move the pointer in any way. If the internal pointer points beyond the end of the elements list, current returns false.

Warning: if the array contains empty elements (0 or "", the empty string) then this function will return false for these elements as well. It is undecideable if the current element is just a zero-value or you have traversed beyond the end of the array. To properly traverse an array, use the each function.

Name

each — return next key/value pair from an array

Description

array each(array array);

Returns the current key/value pair from the array array and advances the array cursor. This pair is returned in a four-element array, with the keys 0, 1, key, and value. Elements 0 and key each contain the key name of the array element, and 1 and value contain the data.

Example 1. each() examples

$foo = array( "bob", "fred", "jussi", "jouni" );

$bar = each( $foo );

$bar now contains the following key/value pairs:

0 => 0
1 => 'bob'
key => 0
value => 'bob'

$foo = array( "Robert" => "Bob", "Seppo" => "Sepi" );

$bar = each( $foo );

$bar now contains the following key/value pairs:

0 => 'Robert'
1 => 'Bob'
key => 'Robert'
value => 'Bob'

each is typically used in conjunction with list to traverse an array; for instance,

$HTTP_POST_VARS:

Example 2. Traversing $HTTP_POST_VARS with each()

echo "Values submitted via POST method:<br>";

while ( list( $key, $val ) = each( $HTTP_POST_VARS ) ) { echo "$key => $val<br>";

}

end

See also key, current, reset, next, and prev.

Name

end — set internal pointer of array to last element

Description

end(array array);

end advances array's internal pointer to the last element. See also: current, end next and reset

key

ksort

Name

key — fetch a key from an associative array

Description

mixed key(array array);

key returns the index element of the current array position. See also: current next

Name

ksort — Sort an array by key.

Description

int ksort(array array);

Sorts an array by key, maintaining key to data correlations. This is useful mainly for associative arrays.

Example 1. ksort example

$fruits = array("d"=>"lemon","a"=>"orange","b"=>"banana","c"=>"apple"); ksort($fruits);

for(reset($fruits); $key = key($fruits); next($fruits)) { echo "fruits[$key] = ".$fruits[$key]."\n";

}

This example would display: fruits[a] = orange fruits[b] = banana fruits[c] = apple fruits[d] = lemon

See also asort, arsort, sort, and rsort.

list

Name

list — assign variables as if they were an array

Description

void list(...);

Like array, this is not really a function, but a language construct. list is used to assign a list of variables in one operation.

Example 1. list example

<table>

<tr>

<th>Employee name</th>

<th>Salary</th>

</tr>

<?php

$result = mysql($conn, "SELECT id, name, salary FROM employees"); while (list($id, $name, $salary) = mysql_fetch_row($result)) {

print(" <tr>\n".

" <td><a href=\"info.php3?id=$id\">$name</a></td>\n". " <td>$salary</td>\n".

" </tr>\n");

}

?></table>

pos

Name

next — advance the internal array pointer

Description

mixed next(array array);

Returns the array element in the next place that's pointed by the internal array pointer, or false if there are no more elements. Warning: if the array contains empty elements then this function will return false for these elements as well. To properly traverse an array which may contain empty elements see the each function.

next behaves like current, with one difference. It advances the internal array pointer one place forward before returning the element. That means it returns the next array element and advances the internal array pointer by one. If advancing the internal array pointer results in going beyond the end of the element list, next returns false.

Name

pos — return the current element in an array

Description

mixed pos(array array);

This is an alias for current.

reset

rsort

Name

prev — rewind internal array pointer

Description

mixed prev(array array);

Returns the array element in the previous place that's pointed by the internal array pointer, or false if there are no more elements. Warning: if the array contains empty elements then this function will return false for these elements as well. To properly traverse an array which may contain empty elements see the each function.

prev behaves just like next, except it rewinds the internal array pointer one place instead of advancing it.

Name

reset — set internal pointer of array to first element

Description

reset(array array);

reset rewinds array's internal pointer to the first element. See also: current, next prev and reset

Name

rsort — Sort an array in reverse order

Description

void rsort(array array);

This function sorts an array in reverse order (highest to lowest).

Example 1. rsort example

$fruits = array("lemon","orange","banana","apple"); rsort($fruits);

for(reset($fruits); $key = key($fruits); next($fruits)) { echo "fruits[$key] = ".$fruits[$key]."\n";

}

This example would display: fruits[0] = orange fruits[1] = lemon fruits[2] = banana fruits[3] = apple The fruits have been sorted in reverse alphabetical order.

See also arsort, asort, ksort, sort and usort.

sizeof

Name

sizeof — get size of array

Description

int sizeof(array array);

sort

Returns the number of elements in the array. See also: count

Name

sort — Sort an array

Description

void sort(array array);

This function sorts an array. Elements will be arranged from lowest to highest when this function has completed.

Example 1. sort example

$fruits = array("lemon","orange","banana","apple"); sort($fruits);

for(reset($fruits); $key = key($fruits); next($fruits)) { echo "fruits[$key] = ".$fruits[$key]."\n";

}

This example would display: fruits[0] = apple fruits[1] = banana fruits[2] = lemon fruits[3] = orange The fruits have been sorted in alphabetical order.

See also arsort, asort, ksort, rsort, and usort.

uasort

Name

uasort — Sort an array with a user-defined comparison function and maintain index association

Description

void uasort(array array, function cmp_function);

uksort

Name

uksort — Sort an array by keys using a user-defined comparison function

Description

void uksort(array array, function cmp_function);

This function will sort the keys of an array using a user-supplied comparison function. If the array you wish to sort needs to be sorted by some non-trivial criteria, you should use this function.

Example 1. uksort example

function mycompare($a, $b) { if ($a == $b) return 0; return ($a > $b) ? -1 : 1;

}

$a = array(4 => "four", 3 => "three", 20 => "twenty", 10 => "ten"); uksort($a, mycompare);

while(list($key, $value) = each($a)) { echo "$key: $value\n";

}

This example would display: 20: twenty 10: ten 4: four 3: three

See also arsort, asort, uasort, ksort, rsort and sort.

usort

Name

usort — Sort an array by values using a user-defined comparison function

Description

void usort(array array, function cmp_function);

This function will sort an array by its values using a user-supplied comparison function. If the array you wish to sort needs to be sorted by some non-trivial criteria, you should use this function.

Example 1. usort example

function cmp($a,$b) {

if ($a == $b) return 0; return ($a > $b) ? -1 : 1;

}

$a = array(3,2,5,6,1); usort($a, cmp);

while(list($key,$value) = each($a)) { echo "$key: $value\n";

}

This example would display: 0: 6 1: 5 2: 3 3: 2 4: 1 Obviously in this trivial case the rsort

function would be more appropriate.

See also arsort, asort, ksort, rsort and sort.