[perl #55158] Hash subscript documentation

# 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