Docbook2Wiki: Initial conversion from Docbook

2008-03-06T22:28:45Z

Initial conversion from Docbook

New page

{{PHP Cookbook/TOC}}

== Introduction ==

Arrays are lists: lists of people, lists of sizes, lists of books. To store a group of related items in a variable, use an array. Like a list on a piece of paper, the elements in array have an order. Usually, each new item comes after the last entry in the array, but just as you can wedge a new entry between a pair of lines already in a paper list, you can do the same with arrays in PHP.

In many languages, there is only one type of array: what is called a ''numerical array'' (or just an array). In a numerical array, if you want to find an entry, you need to know its position within the array, known as an ''index''. Positions are identified by numbers: they start at 0 and work upwards one by one.

In some languages, there is also another type of array: an ''associative array'' , also known as a ''hash'' . In an associative array, indexes aren't integers, but strings. So, in a numerical array of U.S. presidents, "Abraham Lincoln" might have index 16; in the associative-array version, the index might be "Honest." However, while numerical arrays have a strict ordering imposed by their keys, associative arrays frequently make no guarantees about the key ordering. Elements are added in a certain order, but there's no way to determine the order later.

In a few languages, there are both numerical and associative arrays. But, usually the numerical array <tt>$presidents</tt> and the associative array <tt>$presidents</tt> are distinct arrays. Each array type has a specific behavior, and you need to operate on them accordingly. PHP has both numerical and associative arrays, but they don't behave independently.

In PHP, numerical arrays ''are'' associative arrays, and associative arrays ''are'' numerical arrays. So, which kind are they really? Both and neither. The line between them constantly blurs back and forth from one to another. At first, this can be disorienting, especially if you're used to rigid behavior, but soon you'll find this flexibility an asset.

To assign multiple values to an array in one step, use <tt>array( )</tt> :

$fruits = array('Apples', 'Bananas', 'Cantaloupes', 'Dates');

Now, the value of <tt>$fruits[2]</tt> is <tt>'Cantaloupes'</tt>.

<tt>array( )</tt> is very handy when you have a short list of known values. The same array is also produced by:

$fruits[0] = 'Apples';
$fruits[1] = 'Bananas';
$fruits[2] = 'Cantaloupes';
$fruits[3] = 'Dates';

and:

$fruits[ ] = 'Apples';
$fruits[ ] = 'Bananas';
$fruits[ ] = 'Cantaloupes';
$fruits[ ] = 'Dates';

Assigning a value to an array with an empty subscript is shorthand for adding a new element to the end of the array. So, PHP looks up the length of <tt>$fruits</tt> and uses that as the position for the value you're assigning. This assumes, of course, that <tt>$fruits</tt> isn't set to a scalar value, such as 3, and isn't an object. PHP complains if you try to treat a nonarray as an array; however, if this is the first time you're using this variable, PHP automatically converts it to an array and begins indexing at 0.

An identical feature is the function <tt>array_push( )</tt> , which pushes a new value on top of the array stack. However, the <tt>$foo[ ]</tt> notation is the more traditional PHP style; it's also faster. But, sometimes, using <tt>array_push( )</tt> more accurately conveys the stack nature of what you're trying to do, especially when combined with <tt>array_pop( )</tt> , which removes the last element from an array and returns it.

So far, we've placed integers and strings only inside arrays. However, PHP allows you to assign any data type you want to an array element: booleans, integers, floating-point numbers, strings, objects, resources, <tt>NULL</tt>, and even other arrays. So, you can pull arrays or objects directly from a database and place them into an array:

while ($row = mysql_fetch_row($r)) {
$fruits[ ] = $row;
}

while ($obj = mysql_fetch_object($s)) {
$vegetables[ ] = $obj;
}

The first <tt>while</tt> statement creates an array of arrays; the second creates an array of objects. See [[PHP Cookbook/Arrays#Storing Multiple Elements per Key in an Array|Recipe 4.3]] for more on storing multiple elements per key.

To define an array not using integer keys but string keys, you can also use <tt>array( )</tt>, but specify the key/value pairs with <tt>=></tt>:

$fruits = array('red' => 'Apples', 'yellow' => 'Bananas',
'beige' => 'Cantaloupes', 'brown' => 'Dates');

Now, the value of <tt>$fruits['beige']</tt> is <tt>'Cantaloupes'</tt>. This is shorthand for:

$fruits['red'] = 'Apples';
$fruits['yellow'] = 'Bananas';
$fruits['beige'] = 'Cantaloupes';
$fruits['brown'] = 'Dates';

Each array can only hold one unique value for each key. Adding:

$fruits['red'] = 'Strawberry';

overwrites the value of <tt>'Apples'</tt>. However, you can always add another key at a later time:

$fruits['orange'] = 'Orange';

The more you program in PHP, the more you find yourself using associative arrays instead of numerical ones. Instead of creating a numeric array with string values, you can create an associative array and place your values as its keys. If you want, you can then store additional information in the element's value. There's no speed penalty for doing this, and PHP preserves the ordering. Plus, looking up or changing a value is easy because you already know the key.

The easiest way to cycle though an array and operate on all or some of the elements inside is to use <tt>foreach</tt>:

$fruits = array('red' => 'Apples', 'yellow' => 'Bananas',
'beige' => 'Cantaloupes', 'brown' => 'Dates');

foreach ($fruits as $color => $fruit) {
print "$fruit are $color.\n";
}
'''Apples are red.'''
'''Bananas are yellow.'''
'''Cantaloupes are beige.'''
'''Dates are brown.'''

Each time through the loop, PHP assigns the next key to <tt>$color</tt> and the key's value to <tt>$fruit</tt>. When there are no elements left in the array, the loop finishes.

To break an array apart into individual variables, use <tt>list( )</tt> :

$fruits = array('Apples', 'Bananas', 'Cantaloupes', 'Dates');

list($red, $yellow, $beige, $brown) = $fruits;

== Specifying an Array Not Beginning at Element 0 ==

=== Problem ===

You want to assign multiple elements to an array in one step, but you don't want the first index to be 0.

=== Solution ===

Instruct <tt>array( )</tt> to use a different index using the <tt>=></tt> syntax:

$presidents = array(1 => 'Washington', 'Adams', 'Jefferson', 'Madison');

=== Discussion ===

Arrays in PHP, like most, but not all, computer languages begin with the first entry located at index 0. Sometimes, however, the data you're storing makes more sense if the list begins at 1. (And we're not just talking to recovering Pascal programmers here.)

In the Solution, George Washington is the first president, not the zeroth, so if you wish to print a list of the presidents, it's simpler to do this:

foreach ($presidents as $number => $president) {
print "$number: $president\n";
}

than this:

foreach ($presidents as $number => $president) {
$number++;
print "$number: $president\n";
}

The feature isn't restricted to the number 1; any integer works:

$reconstruction_presidents = array(16 => 'Lincoln', 'Johnson', 'Grant');

Also, you can use <tt>=></tt> multiple times in one call:<ref>John Tyler was elected as Harrison's Vice President under the Whig Party platform but was expelled from the party shortly after assuming the presidency following the death of Harrison.</ref>

$whig_presidents = array(9 => 'Harrison', 'Tyler', 12 => 'Taylor', 'Fillmore');

PHP even allows you to use negative numbers in the <tt>array( )</tt> call. (In fact, this method works for noninteger keys, too.) What you'll get is technically an associative array, although as we said, the line between numeric arrays and associative arrays is often blurred in PHP; this is just another one of these cases.

$us_leaders = array(-1 => 'George II', 'George III', 'Washington');

If Washington is the first U.S. leader, George III is the zeroth, and his grandfather George II is the negative-first.

Of course, you can mix and match numeric and string keys in one <tt>array( )</tt> definition, but it's confusing and very rarely needed:

$presidents = array(1 => 'Washington', 'Adams', 'Honest' => 'Lincoln', 'Jefferson');

This is equivalent to:

$presidents[1] = 'Washington'; // Key is 1
$presidents[ ] = 'Adams'; // Key is 1 + 1 => 2
$presidents['Honest'] = 'Lincoln'; // Key is 'Honest'
$presidents[ ] = 'Jefferson'; // Key is 2 + 1 => 3

=== See Also ===

Documentation on <tt>array( )</tt> at ''http://www.php.net/array''.

== Storing Multiple Elements per Key in an Array ==

=== Problem ===

You want to associate multiple elements with a single key.

=== Solution ===

Store the multiple elements in an array:

$fruits = array('red' => array('strawberry','apple'),
'yellow' => array('banana'));

Or, use an object:

while ($obj = mysql_fetch_object($r)) {
$fruits[ ] = $obj;
}

=== Discussion ===

In PHP, keys are unique per array, so you can't associate more than one entry in a key without overwriting the old value. Instead, store your values in an anonymous array:

$fruits['red'][ ] = 'strawberry';
$fruits['red'][ ] = 'apple';
$fruits['yellow'][ ] = 'banana';

Or, if you're processing items in a loop:

while (list($color,$fruit) = mysql_fetch_array($r)) {
$fruits[$color][ ] = $fruit;
}

To print the entries, loop through the array:

foreach ($fruits as $color=>$color_fruit) {
// $color_fruit is an array
foreach ($color_fruit as $fruit) {
print "$fruit is colored $color.<br>";
}
}

Or use the <tt>pc_array_to_comma_string( )</tt> function from [[PHP Cookbook/Arrays#Printing an Array with Commas|Recipe 4.10]].

foreach ($fruits as $color=>$color_fruit) {
print "$color colored fruits include " .
pc_array_to_comma_string($color_fruit) . "<br>";
}

=== See Also ===

[[PHP Cookbook/Arrays#Printing an Array with Commas|Recipe 4.10]] for how to print arrays with commas.

== Initializing an Array to a Range of Integers ==

=== Problem ===

You want to assign a series of consecutive integers to an array.

=== Solution ===

Use <tt>range($start, $stop)</tt> :

$cards = range(1, 52);

=== Discussion ===

For increments other than 1, you can use:

function pc_array_range($start, $stop, $step) {
$array = array();
for ($i = $start; $i <= $stop; $i += $step) {
$array[] = $i;
}
return $array;
}

So, for odd numbers:

$odd = pc_array_range(1, 52, 2);

And, for even numbers:

$even = pc_array_range(2, 52, 2);

=== See Also ===

[[PHP Cookbook/Numbers#Operating on a Series of Integers|Recipe 2.5]] for how to operate on a series of integers; documentation on <tt>range( )</tt> at ''http://www.php.net/range''.

== Iterating Through an Array ==

=== Problem ===

You want to cycle though an array and operate on all or some of the elements inside.

=== Solution ===

Use <tt>foreach</tt> :

foreach ($array as $value) {
// Act on $value
}

Or, to get an array's keys and values:

foreach ($array as $key => $value) {
// Act II
}

Another technique is to use <tt>for</tt> :

for ($key = 0, $size = count($array); $key < $size; $key++) {
// Act III
}

Finally, you can use <tt>each( )</tt> in combination with <tt>list( )</tt> and <tt>while</tt>:

reset($array) // reset internal pointer to beginning of array
while (list($key, $value) = each ($array)) {
// Final Act
}

=== Discussion ===

A <tt>foreach</tt> loop is the shortest way to iterate through an array:

// foreach with values
foreach ($items as $cost) {
...
}

// foreach with keys and values
foreach($items as $item => $cost) {
...
}

With <tt>foreach</tt>, PHP iterates over a copy of the array instead of the actual array. In contrast, when using <tt>each( )</tt> and <tt>for</tt>, PHP iterates over the original array. So, if you modify the array inside the loop, you may (or may not) get the behavior you expect.

If you want to modify the array, reference it directly:

reset($items);
while (list($item, $cost) = each($items)) {
if (! in_stock($item)) {
unset($items[$item]); // address the array directly
}
}

The variables returned by <tt>each( )</tt> aren't aliases for the original values in the array: they're copies, so, if you modify them, it's not reflected in the array. That's why you need to modify <tt>$items[$item]</tt> instead of <tt>$item</tt>.

When using <tt>each( )</tt>, PHP keeps track of where you are inside the loop. After completing a first pass through, to begin again at the start, call <tt>reset( )</tt> to move the pointer back to the front of the array. Otherwise, <tt>each( )</tt> returns <tt>false</tt>.

The <tt>for</tt> loop works only for arrays with consecutive integer keys. Unless you're modifying the size of your array, it's inefficient to recompute the <tt>count( )</tt> of <tt>$items</tt> each time through the loop, so we always use a <tt>$size</tt> variable to hold the array's size:

for ($item = 0, $size = count($items); $item < $size; $item++) {
...
}

If you prefer to count efficiently with one variable, count backwards:

for ($item = count($items) - 1; $item >= 0; $item--) {
...
}

The associative version of the <tt>for</tt> loop is:

for (reset($array); $key = key($array); next($array) ) {
...
}

This fails if any element holds a string that evaluates to <tt>false</tt>, so a perfectly normal value such as 0 causes the loop to end early.

Finally, use <tt>array_map( )</tt> to hand off each element to a function for processing:

// lowercase all words
$lc = array_map('strtolower', $words);

The first argument to <tt>array_map( )</tt> is a function to modify an individual element, and the second is the array to be iterated through.

Generally, we find these functions less flexible than the previous methods, but they are well-suited for the processing and merging of multiple arrays.

If you're unsure if the data you'll be processing is a scalar or an array, you need to protect against calling <tt>foreach</tt> with a non-array. One method is to use <tt>is_array( )</tt> :

if (is_array($items)) {
// foreach loop code for array
} else {
// code for scalar
}

Another method is to coerce all variables into array form using <tt>settype( )</tt> :

settype($items, 'array');
// loop code for arrays

This turns a scalar value into a one element array and cleans up your code at the expense of a little overhead.

=== See Also ===

Documentation on <tt>for</tt> at ''http://www.php.net/for'', <tt>foreach</tt> at ''http://www.php.net/foreach'', <tt>while</tt> at ''http://www.php.net/while'', <tt>each( )</tt> at ''http://www.php.net/each'', <tt>reset( )</tt> at ''http://www.php.net/reset'', and <tt>array_map( )</tt> at ''http://www.php.net/array-map''.

== Deleting Elements from an Array ==

=== Problem ===

You want to remove one or more elements from an array.

=== Solution ===

To delete one element, use <tt>unset( )</tt>:

unset($array[3]);
unset($array['foo']);

To delete multiple noncontiguous elements, also use <tt>unset( )</tt>:

unset($array[3], $array[5]);
unset($array['foo'], $array['bar']);

To delete multiple contiguous elements, use <tt>array_splice( )</tt>:

array_splice($array, $offset, $length);

=== Discussion ===

Using these functions removes all references to these elements from PHP. If you want to keep a key in the array, but with an empty value, assign the empty string to the element:

<nowiki>$array[3] = $array['foo'] = '';</nowiki>

Besides syntax, there's a logical difference between using <tt>unset( )</tt> and assigning <tt><nowiki>''</nowiki></tt> to the element. The first says "This doesn't exist anymore," while the second says "This still exists, but its value is the empty string."

If you're dealing with numbers, assigning <tt>0</tt> may be a better alternative. So, if a company stopped production of the model XL1000 sprocket, it would update its inventory with:

unset($products['XL1000']);

However, if it temporarily ran out of XL1000 sprockets, but was planning to receive a new shipment from the plant later this week, this is better:

$products['XL1000'] = 0;

If you <tt>unset( )</tt> an element, PHP adjusts the array so that looping still works correctly. It doesn't compact the array to fill in the missing holes. This is what we mean when we say that all arrays are associative, even when they appear to be numeric. Here's an example:

<nowiki>// create a "numeric" array
$animals = array('ant', 'bee', 'cat', 'dog', 'elk', 'fox');
print $animals[1]; // prints 'bee'
print $animals[2]; // prints 'cat'
count($animals); // returns 6

// unset( )
unset($animals[1]); // removes element $animals[1] = 'bee'
print $animals[1]; // prints '' and throws an E_NOTICE error
print $animals[2]; // still prints 'cat'
count($animals); // returns 5, even though $array[5] is 'fox'

// add new element
$animals[ ] = 'gnu'; // add new element (not Unix)
print $animals[1]; // prints '', still empty
print $animals[6]; // prints 'gnu', this is where 'gnu' ended up
count($animals); // returns 6

// assign ''
$animals[2] = ''; // zero out value
print $animals[2]; // prints ''
count($animals); // returns 6, count does not decrease</nowiki>

To compact the array into a densely filled numeric array, use <tt>array_values( )</tt> :

$animals = array_values($animals);

Alternatively, <tt>array_splice( )</tt> automatically reindexes arrays to avoid leaving holes:

// create a "numeric" array
$animals = array('ant', 'bee', 'cat', 'dog', 'elk', 'fox');
array_splice($animals, 2, 2);
print_r($animals);
'''Array'''
'''('''
''' [0] => ant'''
''' [1] => bee'''
''' [2] => elk'''
''' [3] => fox'''
''')'''

This is useful if you're using the array as a queue and want to remove items from the queue while still allowing random access. To safely remove the first or last element from an array, use <tt>array_shift( )</tt> and <tt>array_pop( )</tt>, respectively.

However, if you find yourself often running into problems because of holes in arrays, you may not be "thinking PHP." Look at the ways to iterate through the array in [[PHP Cookbook/Arrays#Iterating Through an Array|Recipe 4.5]] that don't involve using a <tt>for</tt> loop.

=== See Also ===

[[PHP Cookbook/Arrays#Iterating Through an Array|Recipe 4.5]] for iteration techniques; documentation on <tt>unset( )</tt> at ''http://www.php.net/unset'', <tt>array_splice( )</tt> at ''http://www.php.net/array-splice'', and <tt>array_values( )</tt> at ''http://www.php.net/array-values''.

== Changing Array Size ==

=== Problem ===

You want to modify the size of an array, either by making it larger or smaller than its current size.

=== Solution ===

Use <tt>array_pad( )</tt> to make an array grow:

<nowiki>// start at three
$array = array('apple', 'banana', 'coconut');

// grow to five
$array = array_pad($array, 5, '');</nowiki>

Now, <tt>count($array)</tt> is <tt>5</tt>, and the last two elements contain the empty string.

To reduce an array, you can use <tt>array_splice( )</tt>:

// no assignment to $array
array_splice($array, 2);

This removes all but the first two elements from <tt>$array</tt>.

=== Discussion ===

Arrays aren't a predeclared size in PHP, so you can resize them on the fly.

To pad an array, use <tt>array_pad( )</tt>. The first argument is the array to be padded. The next argument is the size and direction you want to pad. To pad to the right, use a positive integer; to pad to the left, use a negative one. The third argument is the value to be assigned to the newly created entries. The function returns a modified array and doesn't alter the original.

Here are some examples:

// make a four-element array with 'dates' to the right
$array = array('apple', 'banana', 'coconut');
$array = array_pad($array, 4, 'dates');
print_r($array);
'''Array'''
'''('''
''' [0] => apple'''
''' [1] => banana'''
''' [2] => coconut'''
''' [3] => dates'''
''')'''

// make a six-element array with 'zucchinis' to the left
$array = array_pad($array, -6, 'zucchini');
print_r($array);
'''Array'''
'''('''
''' [0] => zucchini'''
''' [1] => zucchini'''
''' [2] => apple'''
''' [3] => banana'''
''' [4] => coconut'''
''' [5] => dates'''
''')'''

Be careful. <tt>array_pad($array, 4, 'dates')</tt> makes sure an <tt>$array</tt> is ''at least'' four elements long, it doesn't add four ''new'' elements. In this case, if <tt>$array</tt> was already four elements or larger, <tt>array_pad( )</tt> would return an unaltered <tt>$array</tt>.

Also, if you declare a value for a fourth element, <tt>$array[4]</tt>:

$array = array('apple', 'banana', 'coconut');
$array[4] = 'dates';

you end up with a four-element array with indexes <tt>0</tt>, <tt>1</tt>, <tt>2</tt>, and <tt>4</tt>:

Array
(
[0] => apple
[1] => banana
[2] => coconut
[4] => dates
)

PHP essentially turns this into an associative array that happens to have integer keys.

The <tt>array_splice( )</tt> function, unlike <tt>array_pad( )</tt>, has the side-effect of modifying the original array. It returns the spliced out array. That's why you don't assign the return value to <tt>$array</tt>. However, like <tt>array_pad( )</tt>, you can splice from either the right or left. So, calling <tt>array_splice( )</tt> with a value of <tt>-2</tt> chops off the last two elements from the end:

// make a four-element array
$array = array('apple', 'banana', 'coconut', 'dates');

// shrink to three elements
array_splice($array, 3);

// remove last element, equivalent to array_pop( )
array_splice($array, -1);

// only remaining fruits are apple and banana
print_r($array);
'''Array'''
'''('''
''' [0] => apple'''
''' [1] => banana'''
''')'''

=== See Also ===

Documentation on <tt>array_pad( )</tt> at ''http://www.php.net/array-pad'' and <tt>array_splice( )</tt> at ''http://www.php.net/array-splice''.

== Appending One Array to Another ==

=== Problem ===

You want to combine two arrays into one.

=== Solution ===

Use <tt>array_merge( )</tt>:

$garden = array_merge($fruits, $vegetables);

=== Discussion ===

The <tt>array_merge( )</tt> function works with both predefined arrays and arrays defined in place using <tt>array( )</tt>:

$p_languages = array('Perl', 'PHP');
$p_languages = array_merge($p_languages, array('Python'));
print_r($p_languages);
'''Array'''
'''('''
''' [0] => PHP'''
''' [1] => Perl'''
''' [2] => Python'''
''')'''

Accordingly, merged arrays can be either preexisting arrays, as with <tt>$p_languages</tt>, or anonymous arrays, as with <tt>array('Python')</tt>.

You can't use <tt>array_push( )</tt> , because PHP won't automatically flatten out the array into series of independent variables, and you'll end up with a nested array. Thus:

array_push($p_languages, array('Python'));
print_r($p_languages);
'''Array'''
'''('''
''' [0] => PHP'''
''' [1] => Perl'''
''' [2] => Array'''
''' ('''
''' [0] => Python'''
''' )'''

''')'''

Merging arrays with only numerical keys causes the arrays to get renumbered, so values aren't lost. Merging arrays with string keys causes the second array to overwrite the value of any duplicated keys. Arrays with both types of keys exhibit both types of behavior. For example:

$lc = array('a', 'b' => 'b'); // lower-case letters as values
$uc = array('A', 'b' => 'B'); // upper-case letters as values
$ac = array_merge($lc, $uc); // all-cases?
print_r($ac);
'''Array'''
'''('''
''' [0] => a'''
''' [b] => B'''
''' [1] => A'''
''')'''

The uppercase A has been renumbered from index 0 to index 1, to avoid a collision, and merged onto the end. The uppercase B has overwritten the lowercase b and replaced it in the original place within the array.

The <tt>+</tt> operator can also merge arrays. The array on the right overwrites any identically named keys found on the left. It doesn't do any reordering to prevent collisions. Using the previous example:

print_r($a + $b);
print_r($b + $a);
'''Array'''
'''('''
''' [0] => a'''
''' [b] => b'''
''')'''
'''Array'''
'''('''
''' [0] => A'''
''' [b] => B'''
''')'''

Since <tt>a</tt> and <tt>A</tt> both have a key of <tt>0</tt>, and <tt>b</tt> and <tt>B</tt> both have a key of <tt>b</tt>, you end up with a total of only two elements in the merged arrays.

In the first case, <tt>$a + $b</tt> becomes just <tt>$b</tt>, and in the other, <tt>$b + $a</tt> becomes <tt>$a</tt>.

However, if you had two distinctly keyed arrays, this wouldn't be a problem, and the new array would be the union of the two arrays.

=== See Also ===

Documentation on <tt>array_merge( )</tt> at ''http://www.php.net/array-merge''.

== Turning an Array into a String ==

=== Problem ===

You have an array, and you want to convert it into a nicely formatted string.

=== Solution ===

Use <tt>join( )</tt>:

// make a comma delimited list
$string = join(',', $array);

Or loop yourself:

<nowiki>$string = '';

foreach ($array as $key => $value) {
$string .= ",$value";
}

$string = substr($string, 1); // remove leading ","</nowiki>

=== Discussion ===

If you can use <tt>join( )</tt> , do; it's faster than any PHP-based loop. However, <tt>join( )</tt> isn't very flexible. First, it places a delimiter only between elements, not around them. To wrap elements inside HTML bold tags and separate them with commas, do this:

$left = '<b>';
$right = '</b>';

$html = $left . join("$right,$left", $html) . $right;

Second, <tt>join( )</tt> doesn't allow you to discriminate against values. If you want to include a subset of entries, you need to loop yourself:

<nowiki>$string = '';

foreach ($fields as $key => $value) {
// don't include password
if ('password' != $key) {
$string .= ",<b>$value</b>";
}
}

$string = substr($string, 1); // remove leading ","</nowiki>

Notice that a separator is always added to each value, then stripped off outside the loop. While it's somewhat wasteful to add something that will be later subtracted, it's far cleaner and efficient (in most cases) then attempting to embed logic inside of the loop. To wit:

<nowiki>$string = '';
foreach ($fields as $key => $value) {
// don't include password
if ('password' != $value) {
if (!empty($string)) { $string .= ','; }
$string .= "<b>$value</b>";
}
}</nowiki>

Now you have to check <tt>$string</tt> every time you append a value. That's worse than the simple <tt>substr( )</tt> call. Also, prepend the delimiter (in this case a comma) instead of appending it because it's faster to shorten a string from the front than the rear.

=== See Also ===

[[PHP Cookbook/Arrays#Printing an Array with Commas|Recipe 4.10]] for printing an array with commas; documentation on <tt>join( )</tt> at ''http://www.php.net/join'' and <tt>substr( )</tt> at ''http://www.php.net/substr''.

== Printing an Array with Commas ==

=== Problem ===

You want to print out an array with commas separating the elements and with an "and" before the last element if there are more than two elements in the array.

=== Solution ===

Use the <tt>pc_array_to_comma_string( )</tt> function shown in [[PHP Cookbook/Arrays#phpckbk-CHP-4-EX-1|Example 4-1]], which returns the correct string.

<div id="phpckbk-CHP-4-EX-1">
'''Example 4-1. pc_array_to_comma_string( )'''

<nowiki>function pc_array_to_comma_string($array) {

switch (count($array)) {
case 0:
return '';

case 1:
return reset($array);

case 2:
return join(' and ', $array);

default:
$last = array_pop($array);
return join(', ', $array) . ", and $last";
}
}</nowiki>
</div>

=== Discussion ===

If you have a list of items to print, it's useful to print them in a grammatically correct fashion. It looks awkward to display text like this:

$thundercats = array('Lion-O', 'Panthro', 'Tygra', 'Cheetara', 'Snarf');
print 'ThunderCat good guys include ' . join(', ', $thundercats) . '.';
'''ThunderCat good guys include Lion-O, Panthro, Tygra, Cheetara, Snarf'''.

This implementation of this function isn't completely straightforward, since we want <tt>pc_array_to_comma_string( )</tt> to work with all arrays, not just numeric ones beginning at <tt>0</tt>. If restricted only to that subset, for an array of size one, you return <tt>$array[0]</tt>. But, if the array doesn't begin at <tt>0</tt>, <tt>$array[0]</tt> is empty. So, you can use the fact that <tt>reset( )</tt> , which resets an array's internal pointer, also returns the value of the first array element.

For similar reasons, you call <tt>array_pop( )</tt> to grab the end element, instead of assuming it's located at <tt>$array[count($array)-1]</tt>. This allows you to use <tt>join( )</tt> on <tt>$array</tt>.

Also note that the code for case 2 actually also works correctly for case 1. And, the default code works (though inefficiently) for case 2; however, the transitive property doesn't apply, so you can't use the default code on elements of size 1.

=== See Also ===

[[PHP Cookbook/Arrays#Turning an Array into a String|Recipe 4.9]] for turning an array into a string; documentation on <tt>join( )</tt> at ''http://www.php.net/join'', <tt>array_pop( )</tt> at ''http://www.php.net/array-pop'', and <tt>reset( )</tt> at ''http://www.php.net/reset''.

== Checking if a Key Is in an Array ==

=== Problem ===

You want to know if an array contains a certain key.

=== Solution ===

Use <tt>isset( )</tt> :

if (isset($array['key'])) { /* there is a value for 'key' in $array */ }

=== Discussion ===

You can check the definedness of an array element just as you'd for any other variable. See the Introduction to [[PHP Cookbook/Variables|Chapter 5]] for more information about the truth value of variables.

=== See Also ===

Documentation on <tt>isset( )</tt> at ''http://www.php.net/isset''.

== Checking if an Element Is in an Array ==

=== Problem ===

You want to know if an array contains a certain value.

=== Solution ===

Use <tt>in_array( )</tt> :

if (in_array($value, $array)) {
// an element has $value as its value in array $array
}

=== Discussion ===

Use <tt>in_array( )</tt> to check if an element of an array holds a value:

$book_collection = array('Emma', 'Pride and Prejudice', 'Northhanger Abbey');
$book = 'Sense and Sensibility';

if (in_array($book, $book_collection) {
echo 'Own it.';
} else {
echo 'Need it.';
}

The default behavior of <tt>in_array( )</tt> is to compare items using the <tt>==</tt> operator. To use the strict equality check, <tt>===</tt>, pass <tt>true</tt> as the third parameter to <tt>in_array( )</tt>:

$array = array(1, '2', 'three');

in_array(0, $array); // true!
in_array(0, $array, true); // false
in_array(1, $array); // true
in_array(1, $array, true); // true
in_array(2, $array); // true
in_array(2, $array, true); // false

The first check, <tt>in_array(0, $array)</tt>, evaluates to <tt>true</tt> because to compare the number <tt>0</tt> against the string <tt>three</tt>, PHP casts <tt>three</tt> to an integer. Since <tt>three</tt> isn't a numeric string, as is <tt>2</tt>, it becomes <tt>0</tt>. Therefore, <tt>in_array( )</tt> thinks there's a match.

Consequently, when comparing numbers against data that may contain strings, it's safest to use a strict comparison.

If you find yourself calling <tt>in_array( )</tt> multiple times on the same array, it may be better to use an associative array, with the original array elements as the keys in the new associative array. Looking up entries using <tt>in_array( )</tt> takes linear time; with an associative array, it takes constant time.

If you can't create the associative array directly but need to convert from a traditional one with integer keys, use <tt>array_flip( )</tt> to swap the keys and values of an array:

$book_collection = array('Emma',
'Pride and Prejudice',
'Northhanger Abbey');

// convert from numeric array to associative array
$book_collection = array_flip($book_collection);
$book = 'Sense and Sensibility';

if (isset($book_collection[$book])) {
echo 'Own it.';
} else {
echo 'Need it.';
}

Note that doing this condenses multiple keys with the same value into one element in the flipped array.

=== See Also ===

[[PHP Cookbook/Arrays#Finding the Position of an Element in an Array|Recipe 4.13]] for determining the position of an element in an array; documentation on <tt>in_array( )</tt> at ''http://www.php.net/in-array'' and <tt>array_flip( )</tt> at ''http://www.php.net/array-flip''.

== Finding the Position of an Element in an Array ==

=== Problem ===

You want to know if an element is in an array, and, if it is, you want to know where it is located.

=== Solution ===

Use <tt>array_search( )</tt> . It returns the key of the found element or <tt>false</tt>:

$position = array_search($value, $array);
if ($position !== false) {
// the element in position $position has $value as its value in array $array
}

=== Discussion ===

Use <tt>in_array( )</tt> to find if an array contains a value; use <tt>array_search( )</tt> to discover where that value is located. However, because <tt>array_search( )</tt> gracefully handles searches in which the value isn't found, it's better to use <tt>array_search( )</tt> instead of <tt>in_array( )</tt>. The speed difference is minute, and the extra information is potentially useful:

$favorite_foods = array(1 => 'artichokes', 'bread', 'cauliflower', 'deviled eggs');
$food = 'cauliflower';
$position = array_search($food, $favorite_foods);

if ($position !== false) {
echo "My #$position favorite food is $food";
} else {
echo "Blech! I hate $food!";
}

Use the <tt>!==</tt> check against <tt>false</tt> because if your string is found in the array at position <tt>0</tt>, the <tt>if</tt> evaluates to a logical <tt>false</tt>, which isn't what is meant or wanted.

If a value is in the array multiple times, <tt>array_search()</tt> is only guaranteed to return one of the instances, not the first instance.

=== See Also ===

[[PHP Cookbook/Arrays#Checking if an Element Is in an Array|Recipe 4.12]] for checking whether an element is in an array; documentation on <tt>array_search( )</tt> at ''http://www.php.net/array-search''; for more sophisticated searching of arrays using regular expression, see <tt>preg_replace( )</tt> at ''http://www.php.net/preg-replace'' and [[PHP Cookbook/Regular Expressions|Chapter 13]].

== Finding Elements That Pass a Certain Test ==

=== Problem ===

You want to locate entries in an array that meet certain requirements.

=== Solution ===

Use a <tt>foreach</tt> loop:

$movies = array(...);

foreach ($movies as $movie) {
if ($movie['box_office_gross'] < 5000000) { $flops[] = $movie; }
}

Or <tt>array_filter( )</tt> :

$movies = array(...);

function flops($movie) {
return ($movie['box_office_gross'] < 5000000) ? 1 : 0;
}

$flops = array_filter($movies, 'flops');

=== Discussion ===

The <tt>foreach</tt> loops are simple; you scroll through the data and append elements to the return array that match your criteria.

If you want only the first such element, exit the loop using <tt>break</tt> :

foreach ($movies as $movie) {
if ($movie['box_office_gross'] > 200000000) { $blockbuster = $movie; break; }
}

You can also return directly from a function:

function blockbuster($movies) {
foreach ($movies as $movie) {
if ($movie['box_office_gross'] > 200000000) { return $movie; }
}
}

With <tt>array_filter( )</tt> , however, you first create a callback function that returns <tt>true</tt> for values you want to keep and <tt>false</tt> for values you don't. Using <tt>array_filter( )</tt>, you then instruct PHP to process the array as you do in the <tt>foreach</tt>.

It's impossible to bail out early from <tt>array_filter( )</tt>, so <tt>foreach</tt> provides more flexibility and is simpler to understand. Also, it's one of the few cases in which the built-in PHP function doesn't clearly outperform user-level code.

=== See Also ===

Documentation on <tt>array_filter( )</tt> at ''http://www.php.net/array-filter''.

== Finding the Largest or Smallest Valued Element in an Array ==

=== Problem ===

You have an array of elements, and you want to find the largest or smallest valued element. For example, you want to find the appropriate scale when creating a histogram.

=== Solution ===

To find the largest element, use <tt>max( )</tt> :

$largest = max($array);

To find the smallest element, use <tt>min( )</tt> :

$smallest = min($array);

=== Discussion ===

Normally, <tt>max( )</tt> returns the larger of two elements, but if you pass it an array, it searches the entire array instead. Unfortunately, there's no way to find the index of the largest element using <tt>max( )</tt>. To do that, you must sort the array in reverse order to put the largest element in position 0:

arsort($array);

Now the value of the largest element is <tt>$array[0]</tt>.

If you don't want to disturb the order of the original array, make a copy and sort the copy:

$copy = $array;
arsort($copy);

The same concept applies to <tt>min( )</tt> but use <tt>asort( )</tt> instead of <tt>arsort( )</tt>.

=== See Also ===

[[PHP Cookbook/Arrays#Sorting an Array|Recipe 4.17]] for sorting an array; documentation on <tt>max( )</tt> at ''http://www.php.net/max'', <tt>min( )</tt> at ''http://www.php.net/min'', <tt>arsort( )</tt> at ''http://www.php.net/arsort'', and <tt>asort( )</tt> at ''http://www.php.net/min''.

== Reversing an Array ==

=== Problem ===

You want to reverse the order of the elements in an array.

=== Solution ===

Use <tt>array_reverse( )</tt> :

$array = array('Zero', 'One', 'Two');
$reversed = array_reverse($array);

=== Discussion ===

The <tt>array_reverse( )</tt> function reverses the elements in an array. However, it's often possible to avoid this operation. If you wish to reverse an array you've just sorted, modify the sort to do the inverse. If you want to reverse a list you're about to loop through and process, just invert the loop. Instead of:

for ($i = 0, $size = count($array); $i < $size; $i++) {
...
}

do the following:

for ($i = count($array) - 1; $i >=0 ; $i--) {
...
}

However, as always, use a <tt>for</tt> loop only on a tightly packed array.

Another alternative would be, if possible, to invert the order elements are placed into the array. For instance, if you're populating an array from a series of rows returned from a database, you should be able to modify the query to <tt>ORDER DESC</tt>. See your database manual for the exact syntax for your database.

=== See Also ===

Documentation on <tt>array_reverse( )</tt> at ''http://www.php.net/array-reverse''.

== Sorting an Array ==

=== Problem ===

You want to sort an array in a specific way.

=== Solution ===

To sort an array using the traditional definition of sort, use <tt>sort( )</tt> :

$states = array('Delaware', 'Pennsylvania', 'New Jersey');
sort($states);

To sort numerically, pass <tt>SORT_NUMERIC</tt> as the second argument to <tt>sort( )</tt>.

$scores = array(1, 10, 2, 20);
sort($scores, SORT_NUMERIC);

This resorts the numbers in ascending order <tt>(1, 2, 10, 20)</tt> instead of lexicographical order <tt>(1, 10, 2, 20)</tt>.

=== Discussion ===

The <tt>sort( )</tt> function doesn't preserve the key/value association between elements; instead, entries are reindexed starting at <tt>0</tt> and going upward. (The one exception to this rule is a one-element array; its lone element doesn't have its index reset to <tt>0</tt>. This is fixed as of PHP 4.2.3.)

To preserve the key/value links, use <tt>asort( )</tt>. The <tt>asort( )</tt> function is normally used for associative arrays, but it can also be useful when the indexes of the entries are meaningful:

$states = array(1 => 'Delaware', 'Pennsylvania', 'New Jersey');
asort($states);

while (list($rank, $state) = each($states)) {
print "$state was the #$rank state to join the United States\n";

}

Use <tt>natsort( )</tt> to sort the array using a natural sorting algorithm. Under natural sorting, you can mix strings and numbers inside your elements and still get the right answer.

$tests = array('test1.php', 'test10.php', 'test11.php', 'test2.php');
natsort($tests);

The elements are now ordered: <tt>'test1.php'</tt>, <tt>'test2.php'</tt>, <tt>'test10.php'</tt>, and <tt>'test11.php'</tt>. With natural sorting, the number <tt>10</tt> comes after the number <tt>2</tt>; the opposite occurs under traditional sorting. For case-insensitive natural sorting, use <tt>natcasesort( )</tt>.

To sort the array in reverse order, use <tt>rsort( )</tt> or <tt>arsort( )</tt>, which is like <tt>rsort( )</tt> but also preserves keys. There is no <tt>natrsort( )</tt> or <tt>natcasersort( )</tt>. You can also pass <tt>SORT_NUMERIC</tt> into these functions.

=== See Also ===

[[PHP Cookbook/Arrays#Sorting an Array by a Computable Field|Recipe 4.18]] for sorting with a custom comparison function and [[PHP Cookbook/Arrays#Sorting Multiple Arrays|Recipe 4.19]] for sorting multiple arrays; documentation on <tt>sort( )</tt> at ''http://www.php.net/sort'', <tt>asort( )</tt> at ''http://www.php.net/asort'', <tt>natsort( )</tt> at ''http://www.php.net/natsort'', <tt>natcasesort( )</tt> at ''http://www.php.net/natcasesort'', <tt>rsort( )</tt> at ''http://www.php.net/rsort'', and <tt>arsort( )</tt> at ''http://www.php.net/arsort''.

== Sorting an Array by a Computable Field ==

=== Problem ===

You want to define your own sorting routine.

=== Solution ===

Use <tt>usort( )</tt> in combination with a custom comparison function:

// sort in reverse natural order
function natrsort($a, $b) {
return strnatcmp($b, $a);
}

$tests = array('test1.php', 'test10.php', 'test11.php', 'test2.php');
usort($tests, 'natrsort');

=== Discussion ===

The comparison function must return a value greater that 0 if <tt>$a > $b</tt>, <tt>0</tt> if <tt>$a == $b</tt>, and a value less than 0 if <tt>$a < $b</tt>. To sort in reverse, do the opposite. The function in the Solution, <tt>strnatcmp( )</tt> , obeys those rules.

To reverse the sort, instead of multiplying the return value of <tt>strnatcmp($a, $b)</tt> by <tt>-1</tt>, switch the order of the arguments to <tt>strnatcmp($b, $a)</tt>.

The sort function doesn't need to be a wrapper for an existing sort. For instance, the <tt>pc_date_sort( )</tt> function, shown in [[PHP Cookbook/Arrays#phpckbk-CHP-4-EX-2|Example 4-2]], shows how to sort dates.

<div id="phpckbk-CHP-4-EX-2">
'''Example 4-2. pc_date_sort( )'''

// expects dates in the form of "MM/DD/YYYY"
function pc_date_sort($a, $b) {
list($a_month, $a_day, $a_year) = explode('/', $a);
list($b_month, $b_day, $b_year) = explode('/', $b);

if ($a_year > $b_year ) return 1;
if ($a_year < $b_year ) return -1;

if ($a_month > $b_month) return 1;
if ($a_month < $b_month) return -1;

if ($a_day > $b_day ) return 1;
if ($a_day < $b_day ) return -1;

return 0;
}

$dates = array('12/14/2000', '08/10/2001', '08/07/1999');
usort($dates, 'pc_date_sort');
</div>

While sorting, <tt>usort( )</tt> frequently recomputes the sort function's return values each time it's needed to compare two elements, which slows the sort. To avoid unnecessary work, you can cache the comparison values, as shown in <tt>pc_array_sort( )</tt> in [[PHP Cookbook/Arrays#phpckbk-CHP-4-EX-3|Example 4-3]].

<div id="phpckbk-CHP-4-EX-3">
'''Example 4-3. pc_array_sort( )'''

<nowiki>function pc_array_sort($array, $map_func, $sort_func = '') {
$mapped = array_map($map_func, $array); // cache $map_func( ) values

if ('' == $sort_func) {
asort($mapped); // asort( ) is faster then usort( )
} else {
uasort($mapped, $sort_func); // need to preserve keys
}

while (list($key) = each($mapped)) {
$sorted[ ] = $array[$key]; // use sorted keys
}

return $sorted;
}</nowiki>
</div>

To avoid unnecessary work, <tt>pc_array_sort( )</tt> uses a temporary array, <tt>$mapped</tt>, to cache the return values. It then sorts <tt>$mapped</tt>, using either the default sort order or a user-specified sorting routine. Importantly, it uses a sort that preserves the key/value relationship. By default, it uses <tt>asort( )</tt> because <tt>asort( )</tt> is faster than <tt>uasort( )</tt>. (Slowness in <tt>uasort( )</tt> is the whole reason for <tt>pc_array_sort( )</tt> after all.) Finally, it creates a sorted array, <tt>$sorted</tt>, using the sorted keys in <tt>$mapped</tt> to index the values in the original array.

For small arrays or simple sort functions, <tt>usort( )</tt> is faster, but as the number of computations grows, <tt>pc_array_sort( )</tt> surpasses <tt>usort( )</tt>. The following example sorts elements by their string lengths — a relatively quick custom sort:

function pc_u_length($a, $b) {
$a = strlen($a);
$b = strlen($b);

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

function pc_map_length($a) {
return strlen($a);
}

$tests = array('one', 'two', 'three', 'four', 'five',
'six', 'seven', 'eight', 'nine', 'ten');

// faster for < 5 elements using pc_u_length()
usort($tests, 'pc_u_length');

// faster for >= 5 elements using pc_map_length()
$tests = pc_array_sort($tests, 'pc_map_length');

Here, <tt>pc_array_sort( )</tt> is faster than <tt>usort( )</tt> once the array reaches five elements.

=== See Also ===

[[PHP Cookbook/Arrays#Sorting an Array|Recipe 4.17]] for basic sorting and [[PHP Cookbook/Arrays#Sorting Multiple Arrays|Recipe 4.19]] for sorting multiple arrays; documentation on <tt>usort( )</tt> at ''http://www.php.net/usort'', <tt>asort( )</tt> at ''http://www.php.net/asort'', and <tt>array_map( )</tt> at ''http://www.php.net/array-map''.

== Sorting Multiple Arrays ==

=== Problem ===

You want to sort multiple arrays or an array with multiple dimensions.

=== Solution ===

Use <tt>array_multisort( )</tt> :

To sort multiple arrays simultaneously, pass multiple arrays to <tt>array_multisort( )</tt>:

$colors = array('Red', 'White', 'Blue');
$cities = array('Boston', 'New York', 'Chicago');

array_multisort($colors, $cities);
print_r($colors);
print_r($cities);
'''Array'''
'''('''
''' [0] => Blue'''
''' [1] => Red'''
''' [2] => White'''
''')'''
'''Array'''
'''('''
''' [0] => Chicago'''
''' [1] => Boston'''
''' [2] => New York'''
''')'''

To sort multiple dimensions within a single array, pass the specific array elements:

$stuff = array('colors' => array('Red', 'White', 'Blue'),
'cities' => array('Boston', 'New York', 'Chicago'));

array_multisort($stuff['colors'], $stuff['cities']);
print_r($stuff);
'''Array'''
'''('''
''' [colors] => Array'''
''' ('''
''' [0] => Blue'''
''' [1] => Red'''
''' [2] => White'''
''' )'''

''' [cities] => Array'''
''' ('''
''' [0] => Chicago'''
''' [1] => Boston'''
''' [2] => New York'''
''' )'''

''')'''

To modify the sort type, as in <tt>sort( )</tt>, pass in <tt>SORT_REGULAR</tt>, <tt>SORT_NUMERIC</tt>, or <tt>SORT_STRING</tt> after the array. To modify the sort order, unlike in <tt>sort( )</tt>, pass in <tt>SORT_ASC</tt> or <tt>SORT_DESC</tt> after the array. You can also pass in both a sort type and a sort order after the array.

=== Discussion ===

The <tt>array_multisort( )</tt> function can sort several arrays at once or a multidimensional array by one or more dimensions. The arrays are treated as columns of a table to be sorted by rows. The first array is the main one to sort by; all the items in the other arrays are reordered based on the sorted order of the first array. If items in the first array compare as equal, the sort order is determined by the second array, and so on.

The default sorting values are <tt>SORT_REGULAR</tt> and <tt>SORT_ASC</tt>, and they're reset after each array, so there's no reason to pass either of these two values, except for clarity.

$numbers = array(0, 1, 2, 3);
$letters = array('a', 'b', 'c', 'd');
array_multisort($numbers, SORT_NUMERIC, SORT_DESC,
$letters, SORT_STRING , SORT_DESC);

This example reverses the arrays.

=== See Also ===

[[PHP Cookbook/Arrays#Sorting an Array|Recipe 4.17]] for simple sorting and [[PHP Cookbook/Arrays#Sorting an Array by a Computable Field|Recipe 4.18]] for sorting with a custom function; documentation on <tt>array_multisort( )</tt> at ''http://www.php.net/array-multisort''.

== Sorting an Array Using a Method Instead of a Function ==

=== Problem ===

You want to define a custom sorting routine to order an array. However, instead of using a function, you want to use an object method.

=== Solution ===

Pass in an array holding a class name and method in place of the function name:

usort($access_times, array('dates', 'compare'));

=== Discussion ===

As with a custom sort function, the object method needs to take two input arguments and return 1, 0, or -1, depending if the first parameter is larger than, equal to, or less than the second:

class pc_sort {
// reverse-order string comparison
function strrcmp($a, $b) {
return strcmp($b, $a);
}
}

usort($words, array('pc_sort', 'strrcmp'));

=== See Also ===

[[PHP Cookbook/Classes and Objects|Chapter 7]] for more on classes and objects; [[PHP Cookbook/Arrays#Sorting an Array by a Computable Field|Recipe 4.18]] for more on custom sorting of arrays.

== Randomizing an Array ==

=== Problem ===

You want to scramble the elements of an array in a random order.

=== Solution ===

If you're running PHP 4.3 or above, use <tt>shuffle( )</tt> :

shuffle($array);

If you're running an earlier version, use the <tt>pc_array_shuffle( )</tt> function shown in [[PHP Cookbook/Arrays#phpckbk-CHP-4-EX-4|Example 4-4]].

<div id="phpckbk-CHP-4-EX-4">
'''Example 4-4. pc_array_shuffle( )'''

function pc_array_shuffle($array) {
$i = count($array);

while(--$i) {
$j = mt_rand(0, $i);

if ($i != $j) {
// swap elements
$tmp = $array[$j];
$array[$j] = $array[$i];
$array[$i] = $tmp;
}
}

return $array;
}
</div>

Here's an example:

$cards = range(1,52); // deal out 52 "cards"
$cards = pc_array_shuffle($cards);

=== Discussion ===

There's already a <tt>shuffle( )</tt> function in PHP to shuffle arrays, but as of PHP 4.2.2, it doesn't do its job correctly. The built-in shuffling algorithm tends to favor certain permutations more than others. Elements end up looking randomized, but since each element doesn't have the same chance of ending up in each position, it's not a true shuffle. This is fixed in PHP 4.3.

<tt>pc_array_shuffle( )</tt> , known as the Fisher-Yates shuffle, equally distributes the elements throughout the array. Use it if you run a version of PHP earlier than 4.3. Unlike <tt>shuffle( )</tt>, this function returns the scrambled array instead of modifying it in-place. It also requires a tightly packed array with integer keys.

=== See Also ===

[[PHP Cookbook/Arrays#Shuffling a Deck of Cards|Recipe 4.22]] for a function that simulates shuffling a deck of cards; documentation on <tt>shuffle( )</tt> at ''http://www.php.net/shuffle''.

== Shuffling a Deck of Cards ==

=== Problem ===

You want to shuffle a deck of cards and deal them out.

=== Solution ===

Create a array of 52 integers, shuffle them, and map them to cards:

$suits = array('Clubs', 'Diamonds', 'Hearts', 'Spades');
$cards = array('Ace', 2, 3, 4, 5, 6, 7, 8, 9, 10, 'Jack', 'Queen', 'King');

$deck = pc_array_shuffle(range(0, 51));

while (($draw = array_pop($deck)) != NULL) {
print $cards[$draw / 4] . ' of ' . $suits[$draw % 4] . "\n";
}

This code uses the <tt>pc_array_shuffle( )</tt> function from [[PHP Cookbook/Arrays#Randomizing an Array|Recipe 4.21]].

=== Discussion ===

Here, a pair of arrays, <tt>$suits</tt> and <tt>$cards</tt>, is created to hold the English representation of a card. The numbers <tt>0</tt> through <tt>51</tt> are randomly arranged and assigned to <tt>$deck</tt>. To deal a card, just pop them off the top of the array, treating the array like a literal deck of cards.

It's necessary to add the check against <tt>NULL</tt> inside the <tt>while</tt>, otherwise the loop terminates when you draw the zeroth card. If you modify the deck to contain the numbers 1 through 52, the mathematics of deciding which number belongs to which card becomes more complex.

To deal multiple cards at once, call <tt>array_slice( )</tt>:

array_slice($deck, $cards * -1);

=== See Also ===

[[PHP Cookbook/Arrays#Randomizing an Array|Recipe 4.21]] for a function that randomizes an array; documentation on <tt>array_slice( )</tt> at ''http://www.php.net/array-slice''.

== Removing Duplicate Elements from an Array ==

=== Problem ===

You want to eliminate duplicates from an array.

=== Solution ===

If the array is already complete, use <tt>array_unique( )</tt> , which returns a new array that contains no duplicate values:

$unique = array_unique($array);

If you create the array while processing results, here is a technique for numerical arrays:

foreach ($_REQUEST['fruits'] as $fruit) {
if (!in_array($array, $fruit)) { $array[ ] = $fruit; }
}

Here's one for associative arrays:

foreach ($_REQUEST['fruits'] as $fruit) {
$array[$fruit] = $fruit;
}

=== Discussion ===

Once processing is completed, <tt>array_unique( )</tt> is the best way to eliminate duplicates. But, if you're inside a loop, you can eliminate the duplicate entries from appearing by checking if they're already in the array.

An even faster method than using <tt>in_array( )</tt> is to create a hybrid array in which the key and the value for each element are the same. This eliminates the linear check of <tt>in_array( )</tt> but still allows you to take advantage of the array family of functions that operate over the values of an array instead of the keys.

In fact, it's faster to use the associative array method and then call <tt>array_values( )</tt> on the result (or, for that matter, <tt>array_keys( )</tt> , but <tt>array_values( )</tt> is slightly faster) than to create a numeric array directly with the overhead of <tt>in_array( )</tt>.

=== See Also ===

Documentation on <tt>array_unique( )</tt> at ''http://www.php.net/array-unique''.

== Finding the Union, Intersection, or Difference of Two Arrays ==

=== Problem ===

You have a pair of arrays, and you want to find their union (all the elements), intersection (elements in both, not just one), or difference (in one but not both).

=== Solution ===

To compute the union:

$union = array_unique(array_merge($a, $b));

To compute the intersection:

$intersection = array_intersect($a, $b);

To find the simple difference:

$difference = array_diff($a, $b);

And for the symmetric difference:

$difference = array_merge(array_diff($a, $b), array_diff($b, $a));

=== Discussion ===

Many necessary components for these calculations are built into PHP, it's just a matter of combining them in the proper sequence.

To find the union, you merge the two arrays to create one giant array with all values. But, <tt>array_merge( )</tt> allows duplicate values when merging two numeric arrays, so you call <tt>array_unique( )</tt> to filter them out. This can leave gaps between entries because <tt>array_unique( )</tt> doesn't compact the array. It isn't a problem, however, as <tt>foreach</tt> and <tt>each( )</tt> handle sparsely filled arrays without a hitch.

The function to calculate the intersection is simply named <tt>array_intersection( )</tt> and requires no additional work on your part.

The <tt>array_diff( )</tt> function returns an array containing all the unique elements in <tt>$old</tt> that aren't in <tt>$new</tt>. This is known as the ''simple difference'':

$old = array('To', 'be', 'or', 'not', 'to', 'be');
$new = array('To', 'be', 'or', 'whatever');
$difference = array_diff($old, $new);
'''Array'''
'''('''
''' [3] => not'''
''' [4] => to'''
''')'''

The resulting array, <tt>$difference</tt> contains <tt>'not'</tt> and <tt>'to'</tt>, because <tt>array_diff( )</tt> is case-sensitive. It doesn't contain <tt>'whatever'</tt> because it doesn't appear in <tt>$old</tt>.

To get a reverse difference, or in other words, to find the unique elements in <tt>$new</tt> that are lacking in <tt>$old</tt>, flip the arguments:

$old = array('To', 'be', 'or', 'not', 'to', 'be');
$new = array('To', 'be', 'or', 'whatever');
$reverse_diff = array_diff($new, $old);
'''Array'''
'''('''
''' [3] => whatever'''
''')'''

The <tt>$reverse_diff</tt> array contains only <tt>'whatever'</tt>.

If you want to apply a function or other filter to <tt>array_diff( )</tt>, roll your own diffing algorithm:

// implement case-insensitive diffing; diff -i

$seen = array( );
foreach ($new as $n) {
$seen[strtolower($n)]++;
}

foreach ($old as $o) {
$o = strtolower($o);
if (!$seen[$o]) { $diff[$o] = $o; }
}

The first <tt>foreach</tt> builds an associative array lookup table. You then loop through <tt>$old</tt> and, if you can't find an entry in our lookup, add the element to <tt>$diff</tt>.

It can be a little faster to combine <tt>array_diff( )</tt> with <tt>array_map( )</tt>:

$diff = array_diff(array_map('strtolower', $old), array_map('strtolower', $new));

The symmetric difference is what's in <tt>$a</tt>, but not <tt>$b</tt>, and what's in <tt>$b</tt>, but not <tt>$a</tt>:

$difference = array_merge(array_diff($a, $b), array_diff($b, $a));

Once stated, the algorithm is straightforward. You call <tt>array_diff( )</tt> twice and find the two differences. Then you merge them together into one array. There's no need to call <tt>array_unique( )</tt>, since you've intentionally constructed these arrays to have nothing in common.

=== See Also ===

Documentation on <tt>array_unique( )</tt> at ''http://www.php.net/array-unique'', <tt>array_intersect( )</tt> at ''http://www.php.net/array-intersect'', <tt>array_diff( )</tt> at ''http://www.php.net/array-diff'', <tt>array_merge( )</tt> at ''http://www.php.net/array-merge'', and <tt>array_map( )</tt> at ''http://www.php.net/array-map''.

== Finding All Element Combinations of an Array ==

=== Problem ===

You want to find all combinations of sets containing some or all of the elements in an array, also called the ''power set'' .

=== Solution ===

Use the <tt>pc_array_power_set( )</tt> function shown in [[PHP Cookbook/Arrays#phpckbk-CHP-4-EX-5|Example 4-5]].

<div id="phpckbk-CHP-4-EX-5">
'''Example 4-5. pc_array_power_set( )'''

function pc_array_power_set($array) {
// initialize by adding the empty set
$results = array(array( ));

foreach ($array as $element)
foreach ($results as $combination)
array_push($results, array_merge(array($element), $combination));

return $results;
}
</div>

This returns an array of arrays holding every combination of elements, including the empty set. For example:

$set = array('A', 'B', 'C');
$power_set = pc_array_power_set($set);

<tt>$power_set</tt> contains eight arrays:

array( );
array('A');
array('B');
array('C');
array('A', 'B');
array('A', 'C');
array('B', 'C');
array('A', 'B', 'C');

=== Discussion ===

First, you include the empty set, <tt>{}</tt> , in the results. After all, one potential combination of a set is to take no elements from it.

The rest of this function relies on the nature of combinations and PHP's implementation of <tt>foreach</tt>. Each new element added to the array increases the number of combinations. The new combinations are all the old combinations alongside the new element; a two-element array containing <tt>A</tt> and <tt>B</tt> generates four possible combinations: <tt>{}</tt>, <tt>{A}</tt>, <tt>{B}</tt>, and <tt>{A,</tt> <tt>B}</tt>. Adding <tt>C</tt> to this set keeps the four previous combinations but also adds four new combinations: <tt>{C}</tt>, <tt>{A,</tt> <tt>C}</tt>, <tt>{B,</tt> <tt>C}</tt>, and <tt>{A,</tt> <tt>B,</tt> <tt>C}</tt>.

Therefore, the outer <tt>foreach</tt> loop moves through every element of the list; the inner <tt>foreach</tt> loops through every previous combination created by earlier elements. This is the tricky bit; you need to know exactly how PHP behaves during a <tt>foreach</tt>.

The <tt>array_merge( )</tt> function combines the element with the earlier combinations. Note, however, the <tt>$results</tt> array added to the new array with <tt>array_push()</tt> is the one that's cycled through in the <tt>foreach</tt>. Normally, adding entries to <tt>$results</tt> causes an infinite loop, but not in PHP, because PHP operates over a copy of the original list. But, when you pop back up a level to the outer loop, and reexecute the <tt>foreach</tt> with the next <tt>$element</tt>, it's reset. So, you can operate directly on <tt>$results</tt> in place and use it as a stack to hold your combinations. By keeping everything as arrays, you're given far more flexibility when it comes to printing out or further subdividing the combinations at a later time.

To remove the empty set, replace the opening line of:

// initialize by adding the empty set
$results = array(array( ));

with:

// initialize by adding the first element
$results = array(array(array_pop($array)));

Since a one-element array has only one combination — itself — popping off an element is identical to making the first pass through the loop. The double <tt>foreach</tt> statements don't know they're really starting their processing with the second element in the array.

To print the results with tabs between elements inside the combination and returns between each combination, use the following:

$array = array('Adam', 'Bret', 'Ceff', 'Dave');

foreach (pc_array_power_set($array) as $combination) {
print join("\t", $combination) . "\n";
}

Here's how to print only three-element sized combinations:

foreach (pc_array_power_set($set) as $combination) {
if (3 == count($combination)) {
print join("\t", $combination) . "\n";
}
}

Iterating over a large set of elements takes a long time. A set of <tt>n</tt> elements generates 2<sup>n+1</sup> sets. In other words, as <tt>n</tt> grows by 1, the number of elements doubles.

=== See Also ===

[[PHP Cookbook/Arrays#Finding All Permutations of an Array|Recipe 4.26]] for a function that finds all permutation of an array.

== Finding All Permutations of an Array ==

=== Problem ===

You have an array of elements and want to compute all the different ways they can be ordered.

=== Solution ===

Use one of the two permutation algorithms discussed next.

=== Discussion ===

The <tt>pc_permute()</tt> function shown in [[PHP Cookbook/Arrays#phpckbk-CHP-4-EX-6|Example 4-6]] is a PHP modification of a basic recursive function.

<div id="phpckbk-CHP-4-EX-6">
'''Example 4-6. pc_permute( )'''

function pc_permute($items, $perms = array( )) {
if (empty($items)) {
print join(' ', $perms) . "\n";
} else {
for ($i = count($items) - 1; $i >= 0; --$i) {
$newitems = $items;
$newperms = $perms;
list($foo) = array_splice($newitems, $i, 1);
array_unshift($newperms, $foo);
pc_permute($newitems, $newperms);
}
}
}
</div>

For example:

pc_permute(split(' ', 'she sells seashells'));
'''she sells seashells'''
'''she seashells sells'''
'''sells she seashells'''
'''sells seashells she'''
'''seashells she sells'''
'''seashells sells she'''

However, while this recursion is elegant, it's inefficient, because it's making copies all over the place. Also, it's not easy to modify the function to return the values instead of printing them out without resorting to a global variable.

The <tt>pc_next_permutation( )</tt> function shown in [[PHP Cookbook/Arrays#phpckbk-CHP-4-EX-7|Example 4-7]], however, is a little slicker. It combines an idea of Mark-Jason Dominus from ''Perl Cookbook'' by Tom Christianson and Nathan Torkington (O'Reilly) with an algorithm from Edsger Dijkstra's classic text ''A Discipline of Programming'' (Prentice-Hall).

<div id="phpckbk-CHP-4-EX-7">
'''Example 4-7. pc_next_permutation( )'''

function pc_next_permutation($p, $size) {
// slide down the array looking for where we're smaller than the next guy
for ($i = $size - 1; $p[$i] >= $p[$i+1]; --$i) { }

// if this doesn't occur, we've finished our permutations
// the array is reversed: (1, 2, 3, 4) => (4, 3, 2, 1)
if ($i == -1) { return false; }

// slide down the array looking for a bigger number than what we found before
for ($j = $size; $p[$j] <= $p[$i]; --$j) { }

// swap them
$tmp = $p[$i]; $p[$i] = $p[$j]; $p[$j] = $tmp;

// now reverse the elements in between by swapping the ends
for (++$i, $j = $size; $i < $j; ++$i, --$j) {
$tmp = $p[$i]; $p[$i] = $p[$j]; $p[$j] = $tmp;
}

return $p;
}

$set = split(' ', 'she sells seashells'); // like array('she', 'sells', 'seashells')
$size = count($set) - 1;
$perm = range(0, $size);
$j = 0;

do {
foreach ($perm as $i) { $perms[$j][] = $set[$i]; }
} while ($perm = pc_next_permutation($perm, $size) and ++$j);

foreach ($perms as $p) {
print join(' ', $p) . "\n";
}
</div>

Dominus's idea is that instead of manipulating the array itself, you can create permutations of integers. You then map the repositioned integers back onto the elements of the array to calculate the true permutation — a nifty idea.

However, this technique still has some shortcomings. Most importantly, to us as PHP programmers, it frequently pops, pushes, and splices arrays, something that's very Perl-centric. Next, when calculating the permutation of integers, it goes through a series of steps to come up with each permutation; because it doesn't remember previous permutations, it therefore begins each time from the original permutation. Why redo work if you can help it?

Dijkstra's algorithm solves this by taking a permutation of a series of integers and returning the next largest permutation. The code is optimized based upon that assumption. By starting with the smallest pattern (which is just the integers in ascending order) and working your way upwards, you can scroll through all permutations one at a time, by plugging the previous permutation back into the function to get the next one. There are hardly any swaps, even in the final swap loop in which you flip the tail.

There's a side benefit. Dominus's recipe needs the total number of permutations for a given pattern. Since this is the factorial of the number of elements in the set, that's a potentially expensive calculation, even with memoization. Instead of computing that number, it's faster to return <tt>false</tt> from <tt>pc_next_permutation( )</tt> when you notice that <tt>$i</tt> <tt>==</tt> <tt>-1</tt>. When that occurs, you're forced outside the array, and you've exhausted the permutations for the phrase.

Two final notes of implementation. Since the size of the set is invariant, you capture it once using <tt>count( )</tt> and pass it into <tt>pc_next_permutation( )</tt>; this is faster than repeatedly calling <tt>count( )</tt> inside the function. Also, since the set is guaranteed by its construction to have unique elements, i.e., there is one and only one instance of each integer, we don't need to need to check for equality inside the first two <tt>for</tt> loops. However, you should include them in case you want to use this recipe on other numeric sets, in which duplicates might occur.

=== See Also ===

[[PHP Cookbook/Arrays#Finding All Element Combinations of an Array|Recipe 4.25]] for a function that finds the power set of an array; Recipe 4.19 in the ''Perl Cookbook'' (O'Reilly); [[PHP Cookbook/Dates and Times|Chapter 3]], ''A Discipline of Programming'' (Prentice-Hall).

== Program: Printing an Array in a Horizontally Columned HTML Table ==

Converting an array into a horizontally columned table places a fixed number of elements in a row. The first set goes in the opening table row, the second set goes in the next row, and so forth. Finally, you reach the final row, where you might need to optionally pad the row with empty table data cells.

The function <tt>pc_grid_horizontal( )</tt> , shown in [[PHP Cookbook/Arrays#phpckbk-CHP-4-EX-8|Example 4-8]], lets you specify an array and number of columns. It assumes your table width is 100%, but you can alter the <tt>$table_width</tt> variable to change this.

<div id="phpckbk-CHP-4-EX-8">
'''Example 4-8. pc_grid_horizontal( )'''

function pc_grid_horizontal($array, $size) {

// compute <td> width %ages
$table_width = 100;
$width = intval($table_width / $size);

// define how our <tr> and <td> tags appear
// sprintf() requires us to use %% to get literal %
$tr = '<tr align="center">';
$td = "<td width=\"$width%%\">%s</td>";

// open table
$grid = "<table width=\"$table_width%\">$tr";

// loop through entries and display in rows of size $sized
// $i keeps track of when we need a new table tow
$i = 0;
foreach ($array as $e) {
$grid .= sprintf($td, $e);
$i++;

// end of a row
// close it up and open a new one
if (!($i % $size)) {
$grid .= "</tr>$tr";
}
}

// pad out remaining cells with blanks
while ($i % $size) {
$grid .= sprintf($td, '&nbsp;');
$i++;
}

// add </tr>, if necessary
$end_tr_len = strlen($tr) * -1;
if (substr($grid, $end_tr_len) != $tr) {
$grid .= '</tr>';
} else {
$grid = substr($grid, 0, $end_tr_len);
}

// close table
$grid .= '</table>';

return $grid;
}
</div>

The function begins by calculating the width of each <tt><td></tt> as a percentage of the total table size. Depending on the number of columns and the overall size, the sum of the <tt><td></tt> widths might not equal the <tt><table></tt> width, but this shouldn't effect the displayed HTML in a noticeable fashion. Next, define the <tt><td></tt> and <tt><tr></tt> tags, using <tt>printf</tt>-style formatting notation. To get the literal <tt>%</tt> needed for the <tt><td></tt> width percentage, use a double <tt>%%</tt>.

The meat of the function is the <tt>foreach</tt> loop through the array in which we append each <tt><td></tt> to the <tt>$grid</tt>. If you reach the end of a row, which happens when the total number of elements processed is a multiple of number of elements in a row, you close and then reopen the <tt><tr></tt>.

Once you finish adding all the elements, you need to pad the final row with blank or empty <tt><td></tt> elements. Put a nonbreaking space inside the data cell instead of leaving it empty to make the table renders properly in the browser. Now, make sure there isn't an extra <tt><tr></tt> at the end of grid, which occurs when the number of elements is an exact multiple of the width (in other words, if you didn't need to add padding cells). Finally, you can close the table.

For example, let's print the names of the 50 U.S. states in a six-column table:

// establish connection to database
$dsn = 'mysql://user:password@localhost/table';
$dbh = DB::connect($dsn);
if (DB::isError($dbh)) { die ($dbh->getMessage( )); }

// query the database for the 50 states
$sql = "SELECT state FROM states";
$sth = $dbh->query($sql);

// load data into array from database
while ($row = $sth->fetchRow(DB_FETCHMODE_ASSOC)) {
$states[ ] = $row['state'];
}

// generate the HTML table
$grid = pc_grid_horizontal($states, 6);

// and print it out
print $grid;

When rendered in a browser, it looks like [[PHP Cookbook/Arrays#phpckbk-CHP-4-FIG-1|Figure 4-1]].

<div id="phpckbk-CHP-4-FIG-1">
'''Figure 4-1. The United States of America'''

[[Image:PHP Cookbook_I_4_tt286.png|The United States of America]]
</div>

Because 50 doesn't divide evenly by six, there are four extra padding cells in the last row.
== Notes ==

<references/>

PHP Cookbook/Arrays - Revision history

Newacct: /* Checking if a Key Is in an Array */

Docbook2Wiki: Initial conversion from Docbook

Evanlenz: 1 revision(s)

Docbook2Wiki: Initial conversion from Docbook

←Older revision		Revision as of 22:32, 29 January 2010
Line 753:		Line 753:

	if (isset($array['key'])) { /* there is a value for 'key' in $array */ }		if (isset($array['key'])) { /* there is a value for 'key' in $array */ }
		+
		+	Or <tt>array_key_exists( )</tt> :
		+
		+	if (array_key_exists('key', $array)) { /* there is a value for 'key' in $array */ }

	=== Discussion ===		=== Discussion ===
Line 760:		Line 764:
	=== See Also ===		=== See Also ===

-	Documentation on <tt>isset( )</tt> at ''http://www.php.net/isset''.	+	Documentation on <tt>isset( )</tt> at ''http://www.php.net/isset'' and <tt>array_key_exists( )</tt> at ''http://www.php.net/array_key_exists''.

	== Checking if an Element Is in an Array ==		== Checking if an Element Is in an Array ==