Document gv_stashpvn

This is already in the API supported by Devel::PPPort, and is
more efficient than gv_stashpv if the length is already known.

p4raw-id: //depot/perl@23644

diff --git a/embed.fnc b/embed.fnc
index 393f941..56fd52c 100644 (file)
--- a/embed.fnc
+++ b/embed.fnc
@@ -262,7 +262,7 @@ Ap  |void   |gv_fullname4   |SV* sv|GV* gv|const char* prefix|bool keepmain
 Ap     |void   |gv_init        |GV* gv|HV* stash|const char* name \
                                |STRLEN len|int multi
 Apd    |HV*    |gv_stashpv     |const char* name|I32 create
-Ap     |HV*    |gv_stashpvn    |const char* name|U32 namelen|I32 create
+Apd    |HV*    |gv_stashpvn    |const char* name|U32 namelen|I32 create
 Apd    |HV*    |gv_stashsv     |SV* sv|I32 create
 Apd    |void   |hv_clear       |HV* tb
 Ap     |void   |hv_delayfree_ent|HV* hv|HE* entry

diff --git a/gv.c b/gv.c
index 937e0d6..a34df79 100644 (file)
--- a/gv.c
+++ b/gv.c
@@ -576,9 +576,9 @@ S_require_errno(pTHX_ GV *gv)
 =for apidoc gv_stashpv
 
 Returns a pointer to the stash for a specified package.  C<name> should
-be a valid UTF-8 string.  If C<create> is set then the package will be
-created if it does not already exist.  If C<create> is not set and the
-package does not exist then NULL is returned.
+be a valid UTF-8 string and must be null-terminated.  If C<create> is set
+then the package will be created if it does not already exist.  If C<create>
+is not set and the package does not exist then NULL is returned.
 
 =cut
 */
@@ -589,6 +589,18 @@ Perl_gv_stashpv(pTHX_ const char *name, I32 create)
     return gv_stashpvn(name, strlen(name), create);
 }
 
+/*
+=for apidoc gv_stashpvn
+
+Returns a pointer to the stash for a specified package.  C<name> should
+be a valid UTF-8 string.  The C<namelen> parameter indicates the length of
+the C<name>, in bytes.  If C<create> is set then the package will be
+created if it does not already exist.  If C<create> is not set and the
+package does not exist then NULL is returned.
+
+=cut
+*/
+
 HV*
 Perl_gv_stashpvn(pTHX_ const char *name, U32 namelen, I32 create)
 {

diff --git a/pod/perlapi.pod b/pod/perlapi.pod
index 1ac07ce..1bdc2f2 100644 (file)
--- a/pod/perlapi.pod
+++ b/pod/perlapi.pod
@@ -883,11 +883,24 @@ Found in file gv.c
 =item gv_stashpv
 
 Returns a pointer to the stash for a specified package.  C<name> should
-be a valid UTF-8 string.  If C<create> is set then the package will be
+be a valid UTF-8 string and must be null-terminated.  If C<create> is set
+then the package will be created if it does not already exist.  If C<create>
+is not set and the package does not exist then NULL is returned.
+
+       HV*     gv_stashpv(const char* name, I32 create)
+
+=for hackers
+Found in file gv.c
+
+=item gv_stashpvn
+
+Returns a pointer to the stash for a specified package.  C<name> should
+be a valid UTF-8 string.  The C<namelen> parameter indicates the length of
+the C<name>, in bytes.  If C<create> is set then the package will be
 created if it does not already exist.  If C<create> is not set and the
 package does not exist then NULL is returned.
 
-       HV*     gv_stashpv(const char* name, I32 create)
+       HV*     gv_stashpvn(const char* name, U32 namelen, I32 create)
 
 =for hackers
 Found in file gv.c