From yoanlin93@gmail.com

This is a bug report for perl from yoanlin93@​gmail.com,
generated with the help of perlbug 1.40 running under perl 5.21.10.

From 0693f6420be846ce8d1b10d4c931b7a6aa7f3134 Mon Sep 17 00​:00​:00 2001
From​: c9s <yoanlin93@​gmail.com>
Date​: Sat, 4 Apr 2015 01​:58​:00 +0800
Subject​: [PATCH] Describe how to store a HV into another HV by using hv_store
MIME-Version​: 1.0
Content-Type​: multipart/mixed; boundary="------------2.1.2"

This is a multi-part message in MIME format.
--------------2.1.2
Content-Type​: text/plain; charset=UTF-8; format=fixed
Content-Transfer-Encoding​: 8bit

pod/perlguts.pod | 11 ++++++++++-
1 file changed, 10 insertions(+), 1 deletion(-)

--------------2.1.2
Content-Type​: text/x-patch; name="0001-Describe-how-to-store-a-HV-into-another-HV-by-using-.patch"
Content-Transfer-Encoding​: 8bit
Content-Disposition​: attachment; filename="0001-Describe-how-to-store-a-HV-into-another-HV-by-using-.patch"

diff --git a/pod/perlguts.pod b/pod/perlguts.pod
index 2c04a33..0fe61a8 100644
--- a/pod/perlguts.pod
+++ b/pod/perlguts.pod
@@ -470,7 +470,16 @@ C<SV*>.  To access the scalar value, you must first dereference the return
 value.  However, you should check to make sure that the return value is
 not NULL before dereferencing it.
 
-The first of these two functions checks if a hash table entry exists, and the 
+To store a HV, you have to create a RV and cast it to SV* to C<hv_store>, 
+for example:
+
+    HV * some_hash = newHV();
+    hv_store(stash, "key", 3, newRV_noinc((SV *) some_hash), 0);
+
+Here we use C<newRV_noinc> instead of C<newRV_inc> because C<newHV> already set
+the reference count to 1.
+
+The first of these two functions below checks if a hash table entry exists, and the 
 second deletes it.
 
     bool  hv_exists(HV*, const char* key, U32 klen);

--------------2.1.2--


---

Site configuration information for perl 5.21.10​:

Configured by c9s at Fri Feb 27 12​:59​:15 CST 2015.

Summary of my perl5 (revision 5 version 21 subversion 10) configuration​:
  Commit id​: e2bb786
  Platform​:
  osname=darwin, osvers=14.1.0, archname=darwin-2level
  uname='darwin c9smba.local 14.1.0 darwin kernel version 14.1.0​: mon dec 22 23​:10​:38 pst 2014; root​:xnu-2782.10.72~2release_x86_64 x86_64 '
  config_args='-des -Dusedevel -Dprefix=/Users/c9s/perl-blead'
  hint=recommended, useposix=true, d_sigaction=define
  useithreads=undef, usemultiplicity=undef
  use64bitint=define, use64bitall=define, uselongdouble=undef
  usemymalloc=n, bincompat5005=undef
  Compiler​:
  cc='cc', ccflags ='-fno-common -DPERL_DARWIN -fno-strict-aliasing -pipe -fstack-protector -I/usr/local/include -I/opt/local/include',
  optimize='-O3',
  cppflags='-fno-common -DPERL_DARWIN -fno-strict-aliasing -pipe -fstack-protector -I/usr/local/include -I/opt/local/include'
  ccversion='', gccversion='4.2.1 Compatible Apple LLVM 6.0 (clang-600.0.54)', gccosandvers=''
  intsize=4, longsize=8, ptrsize=8, doublesize=8, byteorder=12345678, doublekind=3
  d_longlong=define, longlongsize=8, d_longdbl=define, longdblsize=16, longdblkind=3
  ivtype='long', ivsize=8, nvtype='double', nvsize=8, Off_t='off_t', lseeksize=8
  alignbytes=8, prototype=define
  Linker and Libraries​:
  ld='env MACOSX_DEPLOYMENT_TARGET=10.3 cc', ldflags =' -fstack-protector -L/usr/local/lib -L/opt/local/lib'
  libpth=/usr/local/lib /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/../lib/clang/6.0/lib /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib /usr/lib /opt/local/lib
  libs=-lpthread -lgdbm -ldbm -ldl -lm -lutil -lc
  perllibs=-lpthread -ldl -lm -lutil -lc
  libc=, so=dylib, useshrplib=false, libperl=libperl.a
  gnulibc_version=''
  Dynamic Linking​:
  dlsrc=dl_dlopen.xs, dlext=bundle, d_dlsymun=undef, ccdlflags=' '
  cccdlflags=' ', lddlflags=' -bundle -undefined dynamic_lookup -L/usr/local/lib -L/opt/local/lib -fstack-protector'

@​INC for perl 5.21.10​:
  lib
  /Users/c9s/perl-blead/lib/site_perl/5.21.10/darwin-2level
  /Users/c9s/perl-blead/lib/site_perl/5.21.10
  /Users/c9s/perl-blead/lib/5.21.10/darwin-2level
  /Users/c9s/perl-blead/lib/5.21.10
  .

Environment for perl 5.21.10​:
  DYLD_LIBRARY_PATH (unset)
  HOME=/Users/c9s
  LANG=en_US.UTF-8
  LANGUAGE (unset)
  LC_ALL=en_US.UTF-8
  LC_CTYPE=UTF-8
  LD_LIBRARY_PATH (unset)
  LOGDIR (unset)
  PATH=/Users/c9s/perl5/perlbrew/bin​:/Users/c9s/perl5/perlbrew/perls/perl-5.18.2/bin​:/Users/c9s/.phpbrew/php/php-5.5.17/bin​:/Users/c9s/.rvm/bin​:/Users/c9s/src/google/depot_tools​:/usr/local/texlive/2013/bin/x86_64-darwin​:/Users/c9s/Library/Haskell/bin​:/opt/local/Library/Frameworks/Python.framework/Versions/2.7/bin​:/Users/c9s/.phpbrew/bin​:/opt/local/lib/postgresql92/bin​:/opt/local/bin​:/opt/local/sbin​:/Users/c9s/bin​:/Users/c9s/Library/Haskell/bin​:/opt/local/bin​:/opt/local/apache2/bin​:/Users/c9s/.rvm/bin​:/Users/c9s/.rvm/gems/ruby-2.1.1/bin​:/Users/c9s/.rvm/gems/ruby-2.1.1@​global/bin​:/Users/c9s/.rvm/rubies/ruby-2.1.1/bin​:/Users/c9s/bin​:/usr/local/bin​:/usr/bin​:/bin​:/usr/sbin​:/sbin​:/usr/local/git/bin​:/usr/local/go/bin​:/usr/local/MacGPG2/bin​:/usr/texbin​:/Users/c9s/.rvm/bin
  PERLBREW_BASHRC_VERSION=0.73
  PERLBREW_HOME=/Users/c9s/.perlbrew
  PERLBREW_MANPATH=/Users/c9s/perl5/perlbrew/perls/perl-5.18.2/man
  PERLBREW_PATH=/Users/c9s/perl5/perlbrew/bin​:/Users/c9s/perl5/perlbrew/perls/perl-5.18.2/bin
  PERLBREW_PERL=perl-5.18.2
  PERLBREW_ROOT=/Users/c9s/perl5/perlbrew
  PERLBREW_VERSION=0.73
  PERLDOC=-otext
  PERL_BADLANG (unset)
  PERL_CPANM_OPT=-n --mirror http​://cpan.nctu.edu.tw/
  PERL_MM_USE_DEFAULT=1
  SHELL=/bin/zsh

From @jkeenan

On Fri Apr 03 10​:59​:44 2015, yoanlin93@​gmail.com wrote​:

This is a bug report for perl from yoanlin93@​gmail.com,
generated with the help of perlbug 1.40 running under perl 5.21.10.

From 0693f6420be846ce8d1b10d4c931b7a6aa7f3134 Mon Sep 17 00​:00​:00 2001
From​: c9s <yoanlin93@​gmail.com>
Date​: Sat, 4 Apr 2015 01​:58​:00 +0800
Subject​: [PATCH] Describe how to store a HV into another HV by using
hv_store
MIME-Version​: 1.0
Content-Type​: multipart/mixed; boundary="------------2.1.2"

This is a multi-part message in MIME format.
--------------2.1.2
Content-Type​: text/plain; charset=UTF-8; format=fixed
Content-Transfer-Encoding​: 8bit

---
pod/perlguts.pod | 11 ++++++++++-
1 file changed, 10 insertions(+), 1 deletion(-)

--------------2.1.2
Content-Type​: text/x-patch; name="0001-Describe-how-to-store-a-HV-
into-another-HV-by-using-.patch"
Content-Transfer-Encoding​: 8bit
Content-Disposition​: attachment; filename="0001-Describe-how-to-store-
a-HV-into-another-HV-by-using-.patch"

diff --git a/pod/perlguts.pod b/pod/perlguts.pod
index 2c04a33..0fe61a8 100644
--- a/pod/perlguts.pod
+++ b/pod/perlguts.pod
@​@​ -470,7 +470,16 @​@​ C<SV*>. To access the scalar value, you must
first dereference the return
value. However, you should check to make sure that the return value
is
not NULL before dereferencing it.

-The first of these two functions checks if a hash table entry exists,
and the
+To store a HV, you have to create a RV and cast it to SV* to
C<hv_store>,
+for example​:
+
+ HV * some_hash = newHV();
+ hv_store(stash, "key", 3, newRV_noinc((SV *) some_hash), 0);
+
+Here we use C<newRV_noinc> instead of C<newRV_inc> because C<newHV>
already set
+the reference count to 1.
+
+The first of these two functions below checks if a hash table entry
exists, and the
second deletes it.

bool hv_exists(HV*, const char* key, U32 klen);

--------------2.1.2--

Since we're past the point in the release cycle where we would be making changes in the Perl 5 core code, my feeling is that we shouldn't be making unnecessary changes in the documentation of the core code. So I've marked this patch for consideration for 5.23.1.

Nonetheless, it would be good to get feedback from contributors familiar with perlguts and XS on the merits of this documentation change.

Thank you very much.

--
James E Keenan (jkeenan@​cpan.org)

The RT System itself - Status changed from 'new' to 'open'

From @tonycoz

On Fri Apr 03 10​:59​:44 2015, yoanlin93@​gmail.com wrote​:

-The first of these two functions checks if a hash table entry exists,
and the
+To store a HV, you have to create a RV and cast it to SV* to
C<hv_store>,
+for example​:
+
+ HV * some_hash = newHV();
+ hv_store(stash, "key", 3, newRV_noinc((SV *) some_hash), 0);
+
+Here we use C<newRV_noinc> instead of C<newRV_inc> because C<newHV>
already set
+the reference count to 1.
+
+The first of these two functions below checks if a hash table entry
exists, and the

Perhaps we need a more general note that HVs and AVs need an RV to be stored
in an element of a HV or AV visible from perl space.

Some might read this to imply that HV in HV is the only case that needs the RV.

Tony

From @jkeenan

On Mon, 20 Apr 2015 00​:44​:33 GMT, tonyc wrote​:

On Fri Apr 03 10​:59​:44 2015, yoanlin93@​gmail.com wrote​:

-The first of these two functions checks if a hash table entry
exists,
and the
+To store a HV, you have to create a RV and cast it to SV* to
C<hv_store>,
+for example​:
+
+ HV * some_hash = newHV();
+ hv_store(stash, "key", 3, newRV_noinc((SV *) some_hash), 0);
+
+Here we use C<newRV_noinc> instead of C<newRV_inc> because C<newHV>
already set
+the reference count to 1.
+
+The first of these two functions below checks if a hash table entry
exists, and the

Perhaps we need a more general note that HVs and AVs need an RV to be
stored
in an element of a HV or AV visible from perl space.

Some might read this to imply that HV in HV is the only case that
needs the RV.

Tony

Tony, any further thoughts about this ticket?

--
James E Keenan (jkeenan@​cpan.org)