perlapi: Clarify that a literal string must end in a NUL

Some entries already had this.  For those, it standardizes the text.
This commit is contained in:
Karl Williamson 2016-02-03 12:03:09 -07:00
parent 3a8ba71a30
commit 0c395ea597
5 changed files with 40 additions and 35 deletions

16
cop.h
View File

@ -175,8 +175,8 @@ associated with the key.
/*
=for apidoc Amx|SV *|cophh_fetch_pvs|const COPHH *cophh|const char *key|U32 flags
Like L</cophh_fetch_pvn>, but takes a literal string instead of a
string/length pair, and no precomputed hash.
Like L</cophh_fetch_pvn>, but takes a C<NUL>-terminated literal string instead
of a string/length pair, and no precomputed hash.
=cut
*/
@ -281,8 +281,8 @@ be stored with referential integrity, but will be coerced to strings.
/*
=for apidoc Amx|COPHH *|cophh_store_pvs|const COPHH *cophh|const char *key|SV *value|U32 flags
Like L</cophh_store_pvn>, but takes a literal string instead of a
string/length pair, and no precomputed hash.
Like L</cophh_store_pvn>, but takes a C<NUL>-terminated literal string instead
of a string/length pair, and no precomputed hash.
=cut
*/
@ -338,8 +338,8 @@ hash of the key string, or zero if it has not been precomputed.
/*
=for apidoc Amx|COPHH *|cophh_delete_pvs|const COPHH *cophh|const char *key|U32 flags
Like L</cophh_delete_pvn>, but takes a literal string instead of a
string/length pair, and no precomputed hash.
Like L</cophh_delete_pvn>, but takes a C<NUL>-terminated literal string instead
of a string/length pair, and no precomputed hash.
=cut
*/
@ -478,8 +478,8 @@ associated with the key.
/*
=for apidoc Am|SV *|cop_hints_fetch_pvs|const COP *cop|const char *key|U32 flags
Like L</cop_hints_fetch_pvn>, but takes a literal string instead of a
string/length pair, and no precomputed hash.
Like L</cop_hints_fetch_pvn>, but takes a C<NUL>-terminated literal string
instead of a string/length pair, and no precomputed hash.
=cut
*/

41
handy.h
View File

@ -296,47 +296,49 @@ typedef U64TYPE U64;
=head1 SV-Body Allocation
=for apidoc Ama|SV*|newSVpvs|const char* s
Like C<newSVpvn>, but takes a literal C<NUL>-terminated string instead of a
Like C<newSVpvn>, but takes a C<NUL>-terminated literal string instead of a
string/length pair.
=for apidoc Ama|SV*|newSVpvs_flags|const char* s|U32 flags
Like C<newSVpvn_flags>, but takes a literal C<NUL>-terminated string instead of
Like C<newSVpvn_flags>, but takes a C<NUL>-terminated literal string instead of
a string/length pair.
=for apidoc Ama|SV*|newSVpvs_share|const char* s
Like C<newSVpvn_share>, but takes a literal C<NUL>-terminated string instead of
Like C<newSVpvn_share>, but takes a C<NUL>-terminated literal string instead of
a string/length pair and omits the hash parameter.
=for apidoc Am|void|sv_catpvs_flags|SV* sv|const char* s|I32 flags
Like C<sv_catpvn_flags>, but takes a literal C<NUL>-terminated string instead
Like C<sv_catpvn_flags>, but takes a C<NUL>-terminated literal string instead
of a string/length pair.
=for apidoc Am|void|sv_catpvs_nomg|SV* sv|const char* s
Like C<sv_catpvn_nomg>, but takes a literal string instead of a
string/length pair.
Like C<sv_catpvn_nomg>, but takes a C<NUL>-terminated literal string instead of
a string/length pair.
=for apidoc Am|void|sv_catpvs|SV* sv|const char* s
Like C<sv_catpvn>, but takes a literal string instead of a string/length pair.
Like C<sv_catpvn>, but takes a C<NUL>-terminated literal string instead of a
string/length pair.
=for apidoc Am|void|sv_catpvs_mg|SV* sv|const char* s
Like C<sv_catpvn_mg>, but takes a literal string instead of a
Like C<sv_catpvn_mg>, but takes a C<NUL>-terminated literal string instead of a
string/length pair.
=for apidoc Am|void|sv_setpvs|SV* sv|const char* s
Like C<sv_setpvn>, but takes a literal string instead of a string/length pair.
Like C<sv_setpvn>, but takes a C<NUL>-terminated literal string instead of a
string/length pair.
=for apidoc Am|void|sv_setpvs_mg|SV* sv|const char* s
Like C<sv_setpvn_mg>, but takes a literal string instead of a
Like C<sv_setpvn_mg>, but takes a C<NUL>-terminated literal string instead of a
string/length pair.
=for apidoc Am|SV *|sv_setref_pvs|const char* s
Like C<sv_setref_pvn>, but takes a literal string instead of a
string/length pair.
Like C<sv_setref_pvn>, but takes a C<NUL>-terminated literal string instead of
a string/length pair.
=head1 Memory Management
=for apidoc Ama|char*|savepvs|const char* s
Like C<savepvn>, but takes a literal C<NUL>-terminated string instead of a
Like C<savepvn>, but takes a C<NUL>-terminated literal string instead of a
string/length pair.
=for apidoc Ama|char*|savesharedpvs|const char* s
@ -346,23 +348,26 @@ which is shared between threads.
=head1 GV Functions
=for apidoc Am|HV*|gv_stashpvs|const char* name|I32 create
Like C<gv_stashpvn>, but takes a literal string instead of a string/length pair.
Like C<gv_stashpvn>, but takes a C<NUL>-terminated literal string instead of a
string/length pair.
=head1 Hash Manipulation Functions
=for apidoc Am|SV**|hv_fetchs|HV* tb|const char* key|I32 lval
Like C<hv_fetch>, but takes a literal string instead of a string/length pair.
Like C<hv_fetch>, but takes a C<NUL>-terminated literal string instead of a
string/length pair.
=for apidoc Am|SV**|hv_stores|HV* tb|const char* key|NULLOK SV* val
Like C<hv_store>, but takes a literal string instead of a string/length pair
Like C<hv_store>, but takes a C<NUL>-terminated literal string instead of a
string/length pair
and omits the hash parameter.
=head1 Lexer interface
=for apidoc Amx|void|lex_stuff_pvs|const char *pv|U32 flags
Like L</lex_stuff_pvn>, but takes a literal string instead of a
string/length pair.
Like L</lex_stuff_pvn>, but takes a C<NUL>-terminated literal string instead of
a string/length pair.
=cut
*/

8
hv.h
View File

@ -543,8 +543,8 @@ struct refcounted_he {
/*
=for apidoc m|SV *|refcounted_he_fetch_pvs|const struct refcounted_he *chain|const char *key|U32 flags
Like L</refcounted_he_fetch_pvn>, but takes a literal string instead of
a string/length pair, and no precomputed hash.
Like L</refcounted_he_fetch_pvn>, but takes a C<NUL>-terminated literal string
instead of a string/length pair, and no precomputed hash.
=cut
*/
@ -555,8 +555,8 @@ a string/length pair, and no precomputed hash.
/*
=for apidoc m|struct refcounted_he *|refcounted_he_new_pvs|struct refcounted_he *parent|const char *key|SV *value|U32 flags
Like L</refcounted_he_new_pvn>, but takes a literal string instead of
a string/length pair, and no precomputed hash.
Like L</refcounted_he_new_pvn>, but takes a C<NUL>-terminated literal string
instead of a string/length pair, and no precomputed hash.
=cut
*/

8
pad.h
View File

@ -500,8 +500,8 @@ Clone the state variables associated with running and compiling pads.
/*
=for apidoc Am|PADOFFSET|pad_add_name_pvs|const char *name|U32 flags|HV *typestash|HV *ourstash
Exactly like L</pad_add_name_pvn>, but takes a literal string instead
of a string/length pair.
Exactly like L</pad_add_name_pvn>, but takes a C<NUL>-terminated literal string
instead of a string/length pair.
=cut
*/
@ -512,8 +512,8 @@ of a string/length pair.
/*
=for apidoc Am|PADOFFSET|pad_findmy_pvs|const char *name|U32 flags
Exactly like L</pad_findmy_pvn>, but takes a literal string instead
of a string/length pair.
Exactly like L</pad_findmy_pvn>, but takes a C<NUL>-terminated literal string
instead of a string/length pair.
=cut
*/

View File

@ -183,7 +183,7 @@ given literal string with the new scope.
=item LEAVE_with_name(name)
Same as C<LEAVE>, but when debugging is enabled it first checks that the
scope has the given name. Name must be a literal string.
scope has the given name. C<name> must be a C<NUL>-terminated literal string.
=back