list

void list(mixed varname, mixed ...) 

Populates a list of variables with the values of an array.

Returns:

Not applicable.

Description:

This is perhaps the strangest construct (it's not really a function) in the PHP language; it's the only one that's intended to appear on the left side of an assignment statement. To use list(), you place a comma-separated list of variables (which need not exist beforehand) into the argument list, and then assign the value of an array to list(). Each variable listed is then populated with the value of the corresponding element from the array.

• If there are more elements in the array than variables listed, the extra elements are ignored.

• If there are more variables listed than elements in the array, a warning is generated.

• If no value is assigned to list()—that is, it's not on the left side of an assignment statement—a parse error is generated and script execution is terminated.

• If the value on the right side of the assignment statement is not an array, nothing happens.

Elements of the array can be skipped by placing commas into the argument list with no variable between them.

Version:

PHP 3, PHP 4

See also:

array() 
each() 

Example:

Populate variables with values from an array

/* Get all values into variables. */ 
$array = array('Bob', 'Doug', 'Stompin\' Tom'); 
list($bob, $doug, $stom) = $array; 
echo "\n$bob, $doug, $stom\n"; 

/* Just reset these... */ 
$bob = $doug = $stom = ''; 

/* Skip the middle element. $doug will be empty. */ 
list($bob, , $stom) = $array; 
echo "\n$bob, $doug, $stom\n\n"; 

/* Typical example of using list() and each() to iterate over an array */ 
while (list($key, $value) = each($array)) {
    echo "$key => $value\n"; 
} 

Output: 
Bob, Doug, Stompin' Tom 

Bob, , Stompin' Tom 
0 => Bob 
1 => Doug 
2 => Stompin' Tom