Front page | perl.perl5.porters |
Postings from June 2008
[perl #55158] Hash subscript documentation
From:
ian . goodacre @ xtra . co . nz
Date:
June 1, 2008 11:19
Subject:
[perl #55158] Hash subscript documentation
Message ID:
rt-3.6.HEAD-11257-1212322702-1405.55158-75-0@perl.org
# New Ticket Created by ian.goodacre@xtra.co.nz
# Please include the string: [perl #55158]
# in the subject line of all future correspondence about this issue.
# <URL: http://rt.perl.org/rt3/Ticket/Display.html?id=55158 >
This is a bug report for perl from Ian.Goodacre@xtra.co.nz,
generated with the help of perlbug 1.35 running under perl v5.8.8.
-----------------------------------------------------------------
Dear Perl Maintainers,
Please consider changing perldata.pod to provide a little more
information about hash subscripts. I suggest the following, but
please note that I don't know Perl very well and may have made
some mistakes.
*** perldata.pod.orig 2008-04-06 15:56:40.000000000 +1200
--- perldata.pod 2008-06-01 10:11:26.000000000 +1200
***************
*** 685,690 ****
--- 685,726 ----
print "Darwin's First Name is ", $scientists{"Darwin"}, "\n";
+ Hash keys are always strings. Hash subscripts that are not strings
+ are converted to strings before being used as keys.
+
+ A hash subscript may be a bareword, list or other expression. A bareword
+ is treated as if it were a quoted string. A list is joined with the
+ subscript separator C<$;> (see L<perlvar>). Any other expression is
+ evaluated in scalar context and its value is converted to a string.
+
+ Note the difference between arrays, array slices and lists as hash
subscripts.
+ Arrays and array slices are evaluated in scalar context, returning the
number
+ of elements in the array and the last element of the array slice
respectively,
+ while lists are joined with the subscript separator.
+
+ For example:
+
+ # Given the following array
+ @array = ('a', 'b', 'c');
+
+ # The following are equivalent
+ $hash{@array} = 1;
+ $hash{'3'} = 1;
+
+ # The following are equivalent, but different from the above
+ $hash{@array[0,1]} = 1;
+ $hash{'b'} = 1;
+
+ # The following are equivalent but different from all the above
+ $hash{'a', 'b', 'c'} = 1;
+ $hash{(),@array} = 1;
+ $hash{join($;, 'a', 'b', 'c')} = 1;
+
+ Note also that if a reference is used as a hash subscript it is converted
+ to a string representation which cannot be used as a reference and
there is
+ no simple way to convert the string representation back into a reference.
+
+
=head2 Slices
X<slice> X<array, slice> X<hash, slice>
The reference to the subscript separator and the perlvar documentation
would have saved me a lot of time and confusion, and perhaps it would
benefit others like me in the future. I added the bit about references
because while I was searching for the explanation of what was going on
with the lists I kept encountering queries from people who didn't
understand what was happening. If there is a FAQ entry on the issue,
and in particular the issue of not being able to use the string
representation of a reference as a reference, adding a pointer to it
would be even better.
Kind regards,
Ian Goodacre
-----------------------------------------------------------------
---
Flags:
category=docs
severity=wishlist
---
This perlbug was built using Perl v5.8.8 in the Red Hat build system.
It is being executed now by Perl v5.8.8 - Mon Nov 12 14:44:38 EST 2007.
Site configuration information for perl v5.8.8:
Configured by Red Hat, Inc. at Mon Nov 12 14:44:38 EST 2007.
Summary of my perl5 (revision 5 version 8 subversion 8) configuration:
Platform:
osname=linux, osvers=2.6.20-1.3002.fc6xen,
archname=i386-linux-thread-multi
uname='linux xenbuilder1.fedora.redhat.com 2.6.20-1.3002.fc6xen #1
smp mon aug 13 14:21:21 edt 2007 i686 athlon i386 gnulinux '
config_args='-des -Doptimize=-O2 -g -pipe -Wall
-Wp,-D_FORTIFY_SOURCE=2 -fexceptions -fstack-protector
--param=ssp-buffer-size=4 -m32 -march=i386 -mtune=generic
-fasynchronous-unwind-tables -Dversion=5.8.8 -Dmyhostname=localhost
-Dperladmin=root@localhost -Dcc=gcc -Dcf_by=Red Hat, Inc.
-Dinstallprefix=/usr -Dprefix=/usr -Darchname=i386-linux
-Dvendorprefix=/usr -Dsiteprefix=/usr -Duseshrplib -Dusethreads
-Duseithreads -Duselargefiles -Dd_dosuid -Dd_semctl_semun -Di_db
-Ui_ndbm -Di_gdbm -Di_shadow -Di_syslog -Dman3ext=3pm -Duseperlio
-Dinstallusrbinperl=n -Ubincompat5005 -Uversiononly
-Dpager=/usr/bin/less -isr -Dd_gethostent_r_proto -Ud_endhostent_r_proto
-Ud_sethostent_r_proto -Ud_endprotoent_r_proto -Ud_setprotoent_r_proto
-Ud_endservent_r_proto -Ud_setservent_r_proto -Dinc_version_list=5.8.7
5.8.6 5.8.5 -Dscriptdir=/usr/bin'
hint=recommended, useposix=true, d_sigaction=define
usethreads=define use5005threads=undef useithreads=define
usemultiplicity=define
useperlio=define d_sfio=undef uselargefiles=define usesocks=undef
use64bitint=undef use64bitall=undef uselongdouble=undef
usemymalloc=n, bincompat5005=undef
Compiler:
cc='gcc', ccflags ='-D_REENTRANT -D_GNU_SOURCE -fno-strict-aliasing
-pipe -Wdeclaration-after-statement -I/usr/local/include
-D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64 -I/usr/include/gdbm',
optimize='-O2 -g -pipe -Wall -Wp,-D_FORTIFY_SOURCE=2 -fexceptions
-fstack-protector --param=ssp-buffer-size=4 -m32 -march=i386
-mtune=generic -fasynchronous-unwind-tables',
cppflags='-D_REENTRANT -D_GNU_SOURCE -fno-strict-aliasing -pipe
-Wdeclaration-after-statement -I/usr/local/include -I/usr/include/gdbm'
ccversion='', gccversion='4.1.2 20070925 (Red Hat 4.1.2-27)',
gccosandvers=''
intsize=4, longsize=4, ptrsize=4, doublesize=8, byteorder=1234
d_longlong=define, longlongsize=8, d_longdbl=define, longdblsize=12
ivtype='long', ivsize=4, nvtype='double', nvsize=8, Off_t='off_t',
lseeksize=8
alignbytes=4, prototype=define
Linker and Libraries:
ld='gcc', ldflags =' -L/usr/local/lib'
libpth=/usr/local/lib /lib /usr/lib
libs=-lresolv -lnsl -lgdbm -ldb -ldl -lm -lcrypt -lutil -lpthread -lc
perllibs=-lresolv -lnsl -ldl -lm -lcrypt -lutil -lpthread -lc
libc=/lib/libc-2.6.so, so=so, useshrplib=true, libperl=libperl.so
gnulibc_version='2.6'
Dynamic Linking:
dlsrc=dl_dlopen.xs, dlext=so, d_dlsymun=undef, ccdlflags='-Wl,-E
-Wl,-rpath,/usr/lib/perl5/5.8.8/i386-linux-thread-multi/CORE'
cccdlflags='-fPIC', lddlflags='-shared -O2 -g -pipe -Wall
-Wp,-D_FORTIFY_SOURCE=2 -fexceptions -fstack-protector
--param=ssp-buffer-size=4 -m32 -march=i386 -mtune=generic
-fasynchronous-unwind-tables -L/usr/local/lib'
Locally applied patches:
---
@INC for perl v5.8.8:
/usr/lib/perl5/site_perl/5.8.8/i386-linux-thread-multi
/usr/lib/perl5/site_perl/5.8.7/i386-linux-thread-multi
/usr/lib/perl5/site_perl/5.8.6/i386-linux-thread-multi
/usr/lib/perl5/site_perl/5.8.5/i386-linux-thread-multi
/usr/lib/perl5/site_perl/5.8.8
/usr/lib/perl5/site_perl
/usr/lib/perl5/vendor_perl/5.8.8/i386-linux-thread-multi
/usr/lib/perl5/vendor_perl/5.8.7/i386-linux-thread-multi
/usr/lib/perl5/vendor_perl/5.8.6/i386-linux-thread-multi
/usr/lib/perl5/vendor_perl/5.8.5/i386-linux-thread-multi
/usr/lib/perl5/vendor_perl/5.8.8
/usr/lib/perl5/vendor_perl
/usr/lib/perl5/5.8.8/i386-linux-thread-multi
/usr/lib/perl5/5.8.8
.
---
Environment for perl v5.8.8:
HOME=/home/ian
LANG=en_US.UTF-8
LANGUAGE (unset)
LD_LIBRARY_PATH (unset)
LOGDIR (unset)
PATH=/usr/kerberos/bin:/usr/local/bin:/usr/bin:/bin:/usr/X11R6/bin:/home/ian/bin:/sbin
PERL_BADLANG (unset)
SHELL=/bin/bash
-
[perl #55158] Hash subscript documentation
by ian . goodacre @ xtra . co . nz