PERL -- Array and List Functions

Array and List Functions

delete $ASSOC{KEY}

Deletes the specified value from the specified associative array. Returns the deleted value, or the undefined value if nothing was deleted. Deleting from $ENV{} modifies the environment. Deleting from an array bound to a dbm file deletes the entry from the dbm file.

The following deletes all the values of an associative array:

	foreach $key (keys %ARRAY) {
		delete $ARRAY{$key};
	}

(But it would be faster to use the reset command. Saying undef %ARRAY is faster yet.)

each(ASSOC_ARRAY)

each ASSOC_ARRAY

Returns a 2 element array consisting of the key and value for the next value of an associative array, so that you can iterate over it. Entries are returned in an apparently random order. When the array is entirely read, a null array is returned (which when assigned produces a FALSE (0) value). The next call to each() after that will start iterating again. The iterator can be reset only by reading all the elements from the array. You must not modify the array while iterating over it. There is a single iterator for each associative array, shared by all each(), keys() and values() function calls in the program. The following prints out your environment like the printenv program, only in a different order:

	while (($key,$value) = each %ENV) {
		print "$key=$value\n";
	}

See also keys() and values().

grep(EXPR,LIST)

Evaluates EXPR for each element of LIST (locally setting $_ to each element) and returns the array value consisting of those elements for which the expression evaluated to true. In a scalar context, returns the number of times the expression was true.

	@foo = grep(!/^#/, @bar);    # weed out comments

Note that, since $_ is a reference into the array value, it can be used to modify the elements of the array. While this is useful and supported, it can cause bizarre results if the LIST is not a named array.

join(EXPR,LIST)

join(EXPR,ARRAY)

Joins the separate strings of LIST or ARRAY into a single string with fields separated by the value of EXPR, and returns the string. Example:

    
    $_ = join(':',
		$login,$passwd,$uid,$gid,$gcos,$home,$shell);

See split.

keys(ASSOC_ARRAY)

keys ASSOC_ARRAY

Returns a normal array consisting of all the keys of the named associative array. The keys are returned in an apparently random order, but it is the same order as either the values() or each() function produces (given that the associative array has not been modified). Here is yet another way to print your environment:

	@keys = keys %ENV;
	@values = values %ENV;
	while ($#keys >= 0) {
		print pop(@keys), '=', pop(@values), "\n";
	}

or how about sorted by key:

	foreach $key (sort(keys %ENV)) {
		print $key, '=', $ENV{$key}, "\n";
	}

pop(ARRAY)

pop ARRAY

Pops and returns the last value of the array, shortening the array by 1. Has the same effect as

	$tmp = $ARRAY[$#ARRAY--];

If there are no elements in the array, returns the undefined value.

push(ARRAY,LIST)

Treats ARRAY (@ is optional) as a stack, and pushes the values of LIST onto the end of ARRAY. The length of ARRAY increases by the length of LIST. Has the same effect as

    for $value (LIST) {
	    $ARRAY[++$#ARRAY] = $value;
    }

but is more efficient.

reverse(LIST)

reverse LIST

In an array context, returns an array value consisting of the elements of LIST in the opposite order. In a scalar context, returns a string value consisting of the bytes of the first element of LIST in the opposite order.

shift(ARRAY)

shift ARRAY

shift

Shifts the first value of the array off and returns it, shortening the array by 1 and moving everything down. If there are no elements in the array, returns the undefined value. If ARRAY is omitted, shifts the @ARGV array in the main program, and the @_ array in subroutines. (This is determined lexically.) See also unshift(), push() and pop(). Shift() and unshift() do the same thing to the left end of an array that push() and pop() do to the right end.

sort(SUBROUTINE LIST)

sort(LIST)

sort SUBROUTINE LIST

sort BLOCK LIST

sort LIST

Sorts the LIST and returns the sorted array value. Nonexistent values of arrays are stripped out. If SUBROUTINE or BLOCK is omitted, sorts in standard string comparison order. If SUBROUTINE is specified, gives the name of a subroutine that returns an integer less than, equal to, or greater than 0, depending on how the elements of the array are to be ordered. (The <=> and cmp operators are extremely useful in such routines.) SUBROUTINE may be a scalar variable name, in which case the value provides the name of the subroutine to use. In place of a SUBROUTINE name, you can provide a BLOCK as an anonymous, in-line sort subroutine.

In the interests of efficiency the normal calling code for subroutines is bypassed, with the following effects: the subroutine may not be a recursive subroutine, and the two elements to be compared are passed into the subroutine not via @_ but as $a and $b (see example below). They are passed by reference so don't modify $a and $b.

Examples:

	# sort lexically
	@articles = sort @files;

	# same thing, but with explicit sort routine
	@articles = sort {$a cmp $b} @files;

	# same thing in reversed order
	@articles = sort {$b cmp $a} @files;

	# sort numerically ascending
	@articles = sort {$a <=> $b} @files;

	# sort numerically descending
	@articles = sort {$b <=> $a} @files;

	# sort using explicit subroutine name
	sub byage {
	    $age{$a} <=> $age{$b};	# presuming integers
	}
	@sortedclass = sort byage @class;

	sub reverse { $b cmp $a; }
	@harry = ('dog','cat','x','Cain','Abel');
	@george = ('gone','chased','yz','Punished','Axed');
	print sort @harry;
		# prints AbelCaincatdogx
	print sort reverse @harry;
		# prints xdogcatCainAbel
	print sort @george, 'to', @harry;
		# prints AbelAxedCainPunishedcatchaseddoggonetoxyz

splice(ARRAY,OFFSET,LENGTH,LIST)

splice(ARRAY,OFFSET,LENGTH)

splice(ARRAY,OFFSET)

Removes the elements designated by OFFSET and LENGTH from an array, and replaces them with the elements of LIST, if any. Returns the elements removed from the array. The array grows or shrinks as necessary. If LENGTH is omitted, removes everything from OFFSET onward. The following equivalencies hold (assuming $[ == 0):

	push(@a,$x,$y)\h'|3.5i'splice(@a,$#a+1,0,$x,$y)
	pop(@a)\h'|3.5i'splice(@a,-1)
	shift(@a)\h'|3.5i'splice(@a,0,1)
	unshift(@a,$x,$y)\h'|3.5i'splice(@a,0,0,$x,$y)
	$a[$x] = $y\h'|3.5i'splice(@a,$x,1,$y);

Example, assuming array lengths are passed before arrays:
	
	sub aeq {	# compare two array values
		local(@a) = splice(@_,0,shift);
		local(@b) = splice(@_,0,shift);
		return 0 unless @a == @b;	# same len?
		while (@a) {
		    return 0 if pop(@a) ne pop(@b);
		}
		return 1;
	}
	if (&aeq($len,@foo[1..$len],0+@bar,@bar)) { ... }

split(/PATTERN/,EXPR,LIMIT)

split(/PATTERN/,EXPR)

split(/PATTERN/)

split

Splits a string into an array of strings, and returns it. (If not in an array context, returns the number of fields found and splits into the @_ array. (In an array context, you can force the split into @_ by using ?? as the pattern delimiters, but it still returns the array value.)) If EXPR is omitted, splits the $_ string. If PATTERN is also omitted, splits on whitespace (/[\ \t\n]+/). Anything matching PATTERN is taken to be a delimiter separating the fields. (Note that the delimiter may be longer than one character.) If LIMIT is specified, splits into no more than that many fields (though it may split into fewer). If LIMIT is unspecified, trailing null fields are stripped (which potential users of pop() would do well to remember). A pattern matching the null string (not to be confused with a null pattern //, which is just one member of the set of patterns matching a null string) will split the value of EXPR into separate characters at each point it matches that way. For example:

	print join(':', split(/ */, 'hi there'));

produces the output 'h:i:t:h:e:r:e'.

The LIMIT parameter can be used to partially split a line

	($login, $passwd, $remainder) = split(/:/, $_, 3);

(When assigning to a list, if LIMIT is omitted, perl supplies a LIMIT one larger than the number of variables in the list, to avoid unnecessary work. For the list above LIMIT would have been 4 by default. In time critical applications it behooves you not to split into more fields than you really need.)

If the PATTERN contains parentheses, additional array elements are created from each matching substring in the delimiter.

split(/([,-])/,"1-10,20");

produces the array value

(1,'-',10,',',20)

The pattern /PATTERN/ may be replaced with an expression to specify patterns that vary at runtime. (To do runtime compilation only once, use /$variable/o.) As a special case, specifying a space ('\ ') will split on white space just as split with no arguments does, but leading white space does NOT produce a null first field. Thus, split('\ ') can be used to emulate awk's default behavior, whereas split(/\ /) will give you as many null initial fields as there are leading spaces.

Example:

	open(passwd, '/etc/passwd');
	while (<passwd>) {
		($login, $passwd, $uid, $gid, $gcos, $home, $shell)
			= split(/:/);
		...
	}

(Note that $shell above will still have a newline on it. See chop().) See also join.

unshift(ARRAY,LIST)

Does the opposite of a shift. Or the opposite of a push, depending on how you look at it. Prepends list to the front of the array, and returns the number of elements in the new array.

	unshift(ARGV, '-e') unless $ARGV[0] =~ /^-/;

values(ASSOC_ARRAY)

values ASSOC_ARRAY

Returns a normal array consisting of all the values of the named associative array. The values are returned in an apparently random order, but it is the same order as either the keys() or each() function would produce on the same array. See also keys() and each().