Changes the working directory to EXPR, if possible. If EXPR is omitted,
changes to the directory specified by C<$ENV{HOME}>, if set; if not,
changes to the directory specified by C<$ENV{LOGDIR}>. (Under VMS, the
-variable C<$ENV{SYS$LOGIN}> is also checked, and used if it is set.) If
-neither is set, C<chdir> does nothing. It returns true on success,
+variable C<$ENV{'SYS$LOGIN'}> is also checked, and used if it is set.) If
+neither is set, C<chdir> does nothing and fails. It returns true on success,
false otherwise. See the example under C<die>.
On systems that support fchdir(2), you may pass a filehandle or
=item each ARRAY
X<array, iterator>
-=item each EXPR
-
=for Pod::Functions retrieve the next key/value pair from a hash
When called on a hash in list context, returns a 2-element list
print "$key=$value\n";
}
-Starting with Perl 5.14, C<each> can take a scalar EXPR, which must hold a
-reference to an unblessed hash or array. The argument will be dereferenced
-automatically. This aspect of C<each> is considered highly experimental.
-The exact behaviour may change in a future version of Perl.
-
- while (($key,$value) = each $hashref) { ... }
+Starting with Perl 5.14, an experimental feature allowed C<each> to take a
+scalar expression. This experiment has been deemed unsuccessful, and was
+removed as of Perl 5.24.
As of Perl 5.18 you can use a bare C<each> in a C<while> loop,
which will set C<$_> on every iteration.
a recent vintage:
use 5.012; # so keys/values/each work on arrays
- use 5.014; # so keys/values/each work on scalars (experimental)
use 5.018; # so each assigns to $_ in a lone while test
See also C<keys>, C<values>, and C<sort>.
=item keys ARRAY
-=item keys EXPR
-
=for Pod::Functions retrieve list of indices from a hash
Called in list context, returns a list consisting of all the keys of the
as trying has no effect). C<keys @array> in an lvalue context is a syntax
error.
-Starting with Perl 5.14, C<keys> can take a scalar EXPR, which must contain
-a reference to an unblessed hash or array. The argument will be
-dereferenced automatically. This aspect of C<keys> is considered highly
-experimental. The exact behaviour may change in a future version of Perl.
-
- for (keys $hashref) { ... }
- for (keys $obj->get_arrayref) { ... }
+Starting with Perl 5.14, an experimental feature allowed C<keys> to take a
+scalar expression. This experiment has been deemed unsuccessful, and was
+removed as of Perl 5.24.
To avoid confusing would-be users of your code who are running earlier
versions of Perl with mysterious syntax errors, put this sort of thing at
a recent vintage:
use 5.012; # so keys/values/each work on arrays
- use 5.014; # so keys/values/each work on scalars (experimental)
See also C<each>, C<values>, and C<sort>.
=item pop ARRAY
X<pop> X<stack>
-=item pop EXPR
-
=item pop
=for Pod::Functions remove the last element from an array and return it
happen at other times. If ARRAY is omitted, pops the C<@ARGV> array in the
main program, but the C<@_> array in subroutines, just like C<shift>.
-Starting with Perl 5.14, C<pop> can take a scalar EXPR, which must hold a
-reference to an unblessed array. The argument will be dereferenced
-automatically. This aspect of C<pop> is considered highly experimental.
-The exact behaviour may change in a future version of Perl.
-
-To avoid confusing would-be users of your code who are running earlier
-versions of Perl with mysterious syntax errors, put this sort of thing at
-the top of your file to signal that your code will work I<only> on Perls of
-a recent vintage:
-
- use 5.014; # so push/pop/etc work on scalars (experimental)
+Starting with Perl 5.14, an experimental feature allowed C<pop> to take a
+scalar expression. This experiment has been deemed unsuccessful, and was
+removed as of Perl 5.24.
=item pos SCALAR
X<pos> X<match, position>
=item push ARRAY,LIST
X<push> X<stack>
-=item push EXPR,LIST
-
=for Pod::Functions append one or more elements to an array
Treats ARRAY as a stack by appending the values of LIST to the end of
but is more efficient. Returns the number of elements in the array following
the completed C<push>.
-Starting with Perl 5.14, C<push> can take a scalar EXPR, which must hold a
-reference to an unblessed array. The argument will be dereferenced
-automatically. This aspect of C<push> is considered highly experimental.
-The exact behaviour may change in a future version of Perl.
-
-To avoid confusing would-be users of your code who are running earlier
-versions of Perl with mysterious syntax errors, put this sort of thing at
-the top of your file to signal that your code will work I<only> on Perls of
-a recent vintage:
-
- use 5.014; # so push/pop/etc work on scalars (experimental)
+Starting with Perl 5.14, an experimental feature allowed C<push> to take a
+scalar expression. This experiment has been deemed unsuccessful, and was
+removed as of Perl 5.24.
=item q/STRING/
Instead, use C<blessed> (in the L<Scalar::Util> module) for boolean
checks, C<isa> for specific class checks and C<reftype> (also from
L<Scalar::Util>) for type checks. (See L<perlobj> for details and a
-C<blessed/isa> example.)
+C<blessed>/C<isa> example.)
See also L<perlref>.
=item shift ARRAY
X<shift>
-=item shift EXPR
-
=item shift
=for Pod::Functions remove the first element of an array, and return it
established by the C<eval STRING>, C<BEGIN {}>, C<INIT {}>, C<CHECK {}>,
C<UNITCHECK {}>, and C<END {}> constructs.
-Starting with Perl 5.14, C<shift> can take a scalar EXPR, which must hold a
-reference to an unblessed array. The argument will be dereferenced
-automatically. This aspect of C<shift> is considered highly experimental.
-The exact behaviour may change in a future version of Perl.
-
-To avoid confusing would-be users of your code who are running earlier
-versions of Perl with mysterious syntax errors, put this sort of thing at
-the top of your file to signal that your code will work I<only> on Perls of
-a recent vintage:
-
- use 5.014; # so push/pop/etc work on scalars (experimental)
+Starting with Perl 5.14, an experimental feature allowed C<shift> to take a
+scalar expression. This experiment has been deemed unsuccessful, and was
+removed as of Perl 5.24.
See also C<unshift>, C<push>, and C<pop>. C<shift> and C<unshift> do the
same thing to the left end of an array that C<pop> and C<push> do to the
# same thing, but much more efficiently;
# we'll build auxiliary indices instead
# for speed
- my @nums = @caps = ();
+ my (@nums, @caps);
for (@old) {
push @nums, ( /=(\d+)/ ? $1 : undef );
push @caps, fc($_);
=item splice ARRAY
-=item splice EXPR,OFFSET,LENGTH,LIST
-
-=item splice EXPR,OFFSET,LENGTH
-
-=item splice EXPR,OFFSET
-
-=item splice EXPR
-
=for Pod::Functions add or remove elements anywhere in an array
Removes the elements designated by OFFSET and LENGTH from an array, and
# d -- e -- f
# g -- h
-Starting with Perl 5.14, C<splice> can take scalar EXPR, which must hold a
-reference to an unblessed array. The argument will be dereferenced
-automatically. This aspect of C<splice> is considered highly experimental.
-The exact behaviour may change in a future version of Perl.
-
-To avoid confusing would-be users of your code who are running earlier
-versions of Perl with mysterious syntax errors, put this sort of thing at
-the top of your file to signal that your code will work I<only> on Perls of
-a recent vintage:
-
- use 5.014; # so push/pop/etc work on scalars (experimental)
+Starting with Perl 5.14, an experimental feature allowed C<splice> to take a
+scalar expression. This experiment has been deemed unsuccessful, and was
+removed as of Perl 5.24.
=item split /PATTERN/,EXPR,LIMIT
X<split>
printf '<%.5s>', "truncated"; # prints "<trunc>"
printf '<%10.5s>', "truncated"; # prints "< trunc>"
-You can also get the precision from the next argument using C<.*>:
+You can also get the precision from the next argument using C<.*>, or from a
+specified argument (e.g., with C<.*2$>):
printf '<%.6x>', 1; # prints "<000001>"
printf '<%.*x>', 6, 1; # prints "<000001>"
+ printf '<%.*2$x>', 1, 6; # prints "<000001>"
+
+ printf '<%6.*2$x>', 1, 4; # prints "< 0001>"
+
If a precision obtained through C<*> is negative, it counts
as having no precision at all.
printf '<%.*d>', 0, 0; # prints "<>"
printf '<%.*d>', -1, 0; # prints "<0>"
-You cannot currently get the precision from a specified number,
-but it is intended that this will be possible in the future, for
-example using C<.*2$>:
-
- printf '<%.*2$x>', 1, 6; # INVALID, but in future will print
- # "<000001>"
-
=item size
For numeric conversions, you can specify the size to interpret the
Here are some more examples; be aware that when using an explicit
index, the C<$> may need escaping:
- printf "%2\$d %d\n", 12, 34; # will print "34 12\n"
- printf "%2\$d %d %d\n", 12, 34; # will print "34 12 34\n"
- printf "%3\$d %d %d\n", 12, 34, 56; # will print "56 12 34\n"
- printf "%2\$*3\$d %d\n", 12, 34, 3; # will print " 34 12\n"
+ printf "%2\$d %d\n", 12, 34; # will print "34 12\n"
+ printf "%2\$d %d %d\n", 12, 34; # will print "34 12 34\n"
+ printf "%3\$d %d %d\n", 12, 34, 56; # will print "56 12 34\n"
+ printf "%2\$*3\$d %d\n", 12, 34, 3; # will print " 34 12\n"
+ printf "%*1\$.*f\n", 4, 5, 10; # will print "5.0000\n"
=back
function calls the underlying operating system's I<open>(2) function with the
parameters FILENAME, MODE, and PERMS.
+Returns true on success and C<undef> otherwise.
+
The possible values and flag bits of the MODE parameter are
system-dependent; they are available via the standard module C<Fcntl>. See
the documentation of your operating system's I<open>(2) syscall to see
=item unshift ARRAY,LIST
X<unshift>
-=item unshift EXPR,LIST
-
=for Pod::Functions prepend more elements to the beginning of a list
Does the opposite of a C<shift>. Or the opposite of a C<push>,
prepended elements stay in the same order. Use C<reverse> to do the
reverse.
-Starting with Perl 5.14, C<unshift> can take a scalar EXPR, which must hold
-a reference to an unblessed array. The argument will be dereferenced
-automatically. This aspect of C<unshift> is considered highly
-experimental. The exact behaviour may change in a future version of Perl.
-
-To avoid confusing would-be users of your code who are running earlier
-versions of Perl with mysterious syntax errors, put this sort of thing at
-the top of your file to signal that your code will work I<only> on Perls of
-a recent vintage:
-
- use 5.014; # so push/pop/etc work on scalars (experimental)
+Starting with Perl 5.14, an experimental feature allowed C<unshift> to take
+a scalar expression. This experiment has been deemed unsuccessful, and was
+removed as of Perl 5.24.
=item untie VARIABLE
X<untie>
=item values ARRAY
-=item values EXPR
-
=for Pod::Functions return a list of the values in a hash
In list context, returns a list consisting of all the values of the named
for (values %hash) { s/foo/bar/g } # modifies %hash values
for (@hash{keys %hash}) { s/foo/bar/g } # same
-Starting with Perl 5.14, C<values> can take a scalar EXPR, which must hold
-a reference to an unblessed hash or array. The argument will be
-dereferenced automatically. This aspect of C<values> is considered highly
-experimental. The exact behaviour may change in a future version of Perl.
-
- for (values $hashref) { ... }
- for (values $obj->get_arrayref) { ... }
+Starting with Perl 5.14, an experimental feature allowed C<values> to take a
+scalar expression. This experiment has been deemed unsuccessful, and was
+removed as of Perl 5.24.
To avoid confusing would-be users of your code who are running earlier
versions of Perl with mysterious syntax errors, put this sort of thing at
a recent vintage:
use 5.012; # so keys/values/each work on arrays
- use 5.014; # so keys/values/each work on scalars (experimental)
See also C<keys>, C<each>, and C<sort>.