The listing is alphabetical, case insensitive.
+
+=head1 "Gimme" Values
+
+=over 8
+
+=item GIMME
+
+A backward-compatible version of C<GIMME_V> which can only return
+C<G_SCALAR> or C<G_ARRAY>; in a void context, it returns C<G_SCALAR>.
+Deprecated. Use C<GIMME_V> instead.
+
+ U32 GIMME
+
+=for hackers
+Found in file op.h
+
+=item GIMME_V
+
+The XSUB-writer's equivalent to Perl's C<wantarray>. Returns C<G_VOID>,
+C<G_SCALAR> or C<G_ARRAY> for void, scalar or list context,
+respectively.
+
+ U32 GIMME_V
+
+=for hackers
+Found in file op.h
+
+=item G_ARRAY
+
+Used to indicate list context. See C<GIMME_V>, C<GIMME> and
+L<perlcall>.
+
+=for hackers
+Found in file cop.h
+
+=item G_DISCARD
+
+Indicates that arguments returned from a callback should be discarded. See
+L<perlcall>.
+
+=for hackers
+Found in file cop.h
+
+=item G_EVAL
+
+Used to force a Perl C<eval> wrapper around a callback. See
+L<perlcall>.
+
+=for hackers
+Found in file cop.h
+
+=item G_NOARGS
+
+Indicates that no arguments are being sent to a callback. See
+L<perlcall>.
+
+=for hackers
+Found in file cop.h
+
+=item G_SCALAR
+
+Used to indicate scalar context. See C<GIMME_V>, C<GIMME>, and
+L<perlcall>.
+
+=for hackers
+Found in file cop.h
+
+=item G_VOID
+
+Used to indicate void context. See C<GIMME_V> and L<perlcall>.
+
+=for hackers
+Found in file cop.h
+
+
+=back
+
+=head1 Array Manipulation Functions
+
=over 8
=item AvFILL
=for hackers
Found in file av.c
-=item ax
+=item get_av
-Variable which is setup by C<xsubpp> to indicate the stack base offset,
-used by the C<ST>, C<XSprePUSH> and C<XSRETURN> macros. The C<dMARK> macro
-must be called prior to setup the C<MARK> variable.
+Returns the AV of the specified Perl array. If C<create> is set and the
+Perl variable does not exist then it will be created. If C<create> is not
+set and the variable does not exist then NULL is returned.
- I32 ax
+NOTE: the perl_ form of this function is deprecated.
+
+ AV* get_av(const char* name, I32 create)
=for hackers
-Found in file XSUB.h
+Found in file perl.c
-=item bytes_from_utf8
+=item newAV
-Converts a string C<s> of length C<len> from UTF8 into byte encoding.
-Unlike <utf8_to_bytes> but like C<bytes_to_utf8>, returns a pointer to
-the newly-created string, and updates C<len> to contain the new
-length. Returns the original string if no conversion occurs, C<len>
-is unchanged. Do nothing if C<is_utf8> points to 0. Sets C<is_utf8> to
-0 if C<s> is converted or contains all 7bit characters.
+Creates a new AV. The reference count is set to 1.
-NOTE: this function is experimental and may change or be
-removed without notice.
+ AV* newAV()
+
+=for hackers
+Found in file av.c
+
+=item Nullav
+
+Null AV pointer.
- U8* bytes_from_utf8(U8 *s, STRLEN *len, bool *is_utf8)
=for hackers
-Found in file utf8.c
+Found in file av.h
-=item bytes_to_utf8
+=item sortsv
-Converts a string C<s> of length C<len> from ASCII into UTF8 encoding.
-Returns a pointer to the newly-created string, and sets C<len> to
-reflect the new length.
+Sort an array. Here is an example:
-NOTE: this function is experimental and may change or be
-removed without notice.
+ sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale);
- U8* bytes_to_utf8(U8 *s, STRLEN *len)
+See lib/sort.pm for details about controlling the sorting algorithm.
+
+ void sortsv(SV ** array, size_t num_elts, SVCOMPARE_t cmp)
=for hackers
-Found in file utf8.c
+Found in file pp_sort.c
+
+
+=back
+
+=head1 Callback Functions
+
+=over 8
=item call_argv
=for hackers
Found in file perl.c
-=item CLASS
+=item ENTER
-Variable which is setup by C<xsubpp> to indicate the
-class name for a C++ XS constructor. This is always a C<char*>. See C<THIS>.
+Opening bracket on a callback. See C<LEAVE> and L<perlcall>.
- char* CLASS
+ ENTER;
=for hackers
-Found in file XSUB.h
+Found in file scope.h
-=item Copy
+=item eval_pv
-The XSUB-writer's interface to the C C<memcpy> function. The C<src> is the
-source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
-the type. May fail on overlapping copies. See also C<Move>.
+Tells Perl to C<eval> the given string and return an SV* result.
- void Copy(void* src, void* dest, int nitems, type)
+NOTE: the perl_ form of this function is deprecated.
-=for hackers
-Found in file handy.h
+ SV* eval_pv(const char* p, I32 croak_on_error)
-=item croak
+=for hackers
+Found in file perl.c
-This is the XSUB-writer's interface to Perl's C<die> function.
-Normally use this function the same way you use the C C<printf>
-function. See C<warn>.
+=item eval_sv
-If you want to throw an exception object, assign the object to
-C<$@> and then pass C<Nullch> to croak():
+Tells Perl to C<eval> the string in the SV.
- errsv = get_sv("@", TRUE);
- sv_setsv(errsv, exception_object);
- croak(Nullch);
+NOTE: the perl_ form of this function is deprecated.
- void croak(const char* pat, ...)
+ I32 eval_sv(SV* sv, I32 flags)
=for hackers
-Found in file util.c
+Found in file perl.c
-=item CvSTASH
+=item FREETMPS
-Returns the stash of the CV.
+Closing bracket for temporaries on a callback. See C<SAVETMPS> and
+L<perlcall>.
- HV* CvSTASH(CV* cv)
+ FREETMPS;
=for hackers
-Found in file cv.h
-
-=item cv_const_sv
+Found in file scope.h
-If C<cv> is a constant sub eligible for inlining. returns the constant
-value returned by the sub. Otherwise, returns NULL.
+=item LEAVE
-Constant subs can be created with C<newCONSTSUB> or as described in
-L<perlsub/"Constant Functions">.
+Closing bracket on a callback. See C<ENTER> and L<perlcall>.
- SV* cv_const_sv(CV* cv)
+ LEAVE;
=for hackers
-Found in file op.c
+Found in file scope.h
-=item dAX
+=item SAVETMPS
-Sets up the C<ax> variable.
-This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
+Opening bracket for temporaries on a callback. See C<FREETMPS> and
+L<perlcall>.
- dAX;
+ SAVETMPS;
=for hackers
-Found in file XSUB.h
+Found in file scope.h
-=item dITEMS
-Sets up the C<items> variable.
-This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
+=back
- dITEMS;
+=head1 Character classes
-=for hackers
-Found in file XSUB.h
+=over 8
-=item dMARK
+=item isALNUM
-Declare a stack marker variable, C<mark>, for the XSUB. See C<MARK> and
-C<dORIGMARK>.
+Returns a boolean indicating whether the C C<char> is an ASCII alphanumeric
+character (including underscore) or digit.
- dMARK;
+ bool isALNUM(char ch)
=for hackers
-Found in file pp.h
+Found in file handy.h
-=item dORIGMARK
+=item isALPHA
-Saves the original stack mark for the XSUB. See C<ORIGMARK>.
+Returns a boolean indicating whether the C C<char> is an ASCII alphabetic
+character.
- dORIGMARK;
+ bool isALPHA(char ch)
=for hackers
-Found in file pp.h
+Found in file handy.h
-=item dSP
+=item isDIGIT
-Declares a local copy of perl's stack pointer for the XSUB, available via
-the C<SP> macro. See C<SP>.
+Returns a boolean indicating whether the C C<char> is an ASCII
+digit.
- dSP;
+ bool isDIGIT(char ch)
=for hackers
-Found in file pp.h
+Found in file handy.h
-=item dXSARGS
+=item isLOWER
-Sets up stack and mark pointers for an XSUB, calling dSP and dMARK.
-Sets up the C<ax> and C<items> variables by calling C<dAX> and C<dITEMS>.
-This is usually handled automatically by C<xsubpp>.
+Returns a boolean indicating whether the C C<char> is a lowercase
+character.
- dXSARGS;
+ bool isLOWER(char ch)
=for hackers
-Found in file XSUB.h
+Found in file handy.h
-=item dXSI32
+=item isSPACE
-Sets up the C<ix> variable for an XSUB which has aliases. This is usually
-handled automatically by C<xsubpp>.
+Returns a boolean indicating whether the C C<char> is whitespace.
- dXSI32;
+ bool isSPACE(char ch)
=for hackers
-Found in file XSUB.h
+Found in file handy.h
-=item ENTER
+=item isUPPER
-Opening bracket on a callback. See C<LEAVE> and L<perlcall>.
+Returns a boolean indicating whether the C C<char> is an uppercase
+character.
- ENTER;
+ bool isUPPER(char ch)
=for hackers
-Found in file scope.h
+Found in file handy.h
-=item eval_pv
+=item toLOWER
-Tells Perl to C<eval> the given string and return an SV* result.
+Converts the specified character to lowercase.
-NOTE: the perl_ form of this function is deprecated.
+ char toLOWER(char ch)
- SV* eval_pv(const char* p, I32 croak_on_error)
+=for hackers
+Found in file handy.h
+
+=item toUPPER
+
+Converts the specified character to uppercase.
+
+ char toUPPER(char ch)
=for hackers
-Found in file perl.c
+Found in file handy.h
-=item eval_sv
-Tells Perl to C<eval> the string in the SV.
+=back
-NOTE: the perl_ form of this function is deprecated.
+=head1 Cloning an interpreter
- I32 eval_sv(SV* sv, I32 flags)
+=over 8
+
+=item perl_clone
+
+Create and return a new interpreter by cloning the current one.
+
+ PerlInterpreter* perl_clone(PerlInterpreter* interp, UV flags)
=for hackers
-Found in file perl.c
+Found in file sv.c
-=item EXTEND
-Used to extend the argument stack for an XSUB's return values. Once
-used, guarantees that there is room for at least C<nitems> to be pushed
-onto the stack.
+=back
- void EXTEND(SP, int nitems)
+=head1 CV Manipulation Functions
+
+=over 8
+
+=item CvSTASH
+
+Returns the stash of the CV.
+
+ HV* CvSTASH(CV* cv)
=for hackers
-Found in file pp.h
+Found in file cv.h
-=item fbm_compile
+=item get_cv
-Analyses the string in order to make fast searches on it using fbm_instr()
--- the Boyer-Moore algorithm.
+Returns the CV of the specified Perl subroutine. If C<create> is set and
+the Perl subroutine does not exist then it will be declared (which has the
+same effect as saying C<sub name;>). If C<create> is not set and the
+subroutine does not exist then NULL is returned.
- void fbm_compile(SV* sv, U32 flags)
+NOTE: the perl_ form of this function is deprecated.
+
+ CV* get_cv(const char* name, I32 create)
=for hackers
-Found in file util.c
+Found in file perl.c
-=item fbm_instr
+=item Nullcv
-Returns the location of the SV in the string delimited by C<str> and
-C<strend>. It returns C<Nullch> if the string can't be found. The C<sv>
-does not have to be fbm_compiled, but the search will not be as fast
-then.
+Null CV pointer.
- char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags)
=for hackers
-Found in file util.c
+Found in file cv.h
-=item FREETMPS
-Closing bracket for temporaries on a callback. See C<SAVETMPS> and
-L<perlcall>.
+=back
- FREETMPS;
+=head1 Embedding Functions
+
+=over 8
+
+=item load_module
+
+Loads the module whose name is pointed to by the string part of name.
+Note that the actual module name, not its filename, should be given.
+Eg, "Foo::Bar" instead of "Foo/Bar.pm". flags can be any of
+PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT, or PERL_LOADMOD_IMPORT_OPS
+(or 0 for no flags). ver, if specified, provides version semantics
+similar to C<use Foo::Bar VERSION>. The optional trailing SV*
+arguments can be used to specify arguments to the module's import()
+method, similar to C<use Foo::Bar VERSION LIST>.
+
+ void load_module(U32 flags, SV* name, SV* ver, ...)
=for hackers
-Found in file scope.h
+Found in file op.c
-=item getcwd_sv
+=item nothreadhook
-Fill the sv with current working directory
+Stub that provides thread hook for perl_destruct when there are
+no threads.
- int getcwd_sv(SV* sv)
+ int nothreadhook()
=for hackers
-Found in file util.c
+Found in file perl.c
-=item get_av
+=item perl_alloc
-Returns the AV of the specified Perl array. If C<create> is set and the
-Perl variable does not exist then it will be created. If C<create> is not
-set and the variable does not exist then NULL is returned.
+Allocates a new Perl interpreter. See L<perlembed>.
-NOTE: the perl_ form of this function is deprecated.
+ PerlInterpreter* perl_alloc()
- AV* get_av(const char* name, I32 create)
+=for hackers
+Found in file perl.c
+
+=item perl_construct
+
+Initializes a new Perl interpreter. See L<perlembed>.
+
+ void perl_construct(PerlInterpreter* interp)
=for hackers
Found in file perl.c
-=item get_cv
+=item perl_destruct
-Returns the CV of the specified Perl subroutine. If C<create> is set and
-the Perl subroutine does not exist then it will be declared (which has the
-same effect as saying C<sub name;>). If C<create> is not set and the
-subroutine does not exist then NULL is returned.
+Shuts down a Perl interpreter. See L<perlembed>.
-NOTE: the perl_ form of this function is deprecated.
+ int perl_destruct(PerlInterpreter* interp)
- CV* get_cv(const char* name, I32 create)
+=for hackers
+Found in file perl.c
+
+=item perl_free
+
+Releases a Perl interpreter. See L<perlembed>.
+
+ void perl_free(PerlInterpreter* interp)
=for hackers
Found in file perl.c
-=item get_hv
+=item perl_parse
-Returns the HV of the specified Perl hash. If C<create> is set and the
-Perl variable does not exist then it will be created. If C<create> is not
-set and the variable does not exist then NULL is returned.
+Tells a Perl interpreter to parse a Perl script. See L<perlembed>.
-NOTE: the perl_ form of this function is deprecated.
+ int perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env)
- HV* get_hv(const char* name, I32 create)
+=for hackers
+Found in file perl.c
+
+=item perl_run
+
+Tells a Perl interpreter to run. See L<perlembed>.
+
+ int perl_run(PerlInterpreter* interp)
=for hackers
Found in file perl.c
-=item get_sv
+=item require_pv
-Returns the SV of the specified Perl scalar. If C<create> is set and the
-Perl variable does not exist then it will be created. If C<create> is not
-set and the variable does not exist then NULL is returned.
+Tells Perl to C<require> the file named by the string argument. It is
+analogous to the Perl code C<eval "require '$file'">. It's even
+implemented that way; consider using Perl_load_module instead.
NOTE: the perl_ form of this function is deprecated.
- SV* get_sv(const char* name, I32 create)
+ void require_pv(const char* pv)
=for hackers
Found in file perl.c
-=item GIMME
-A backward-compatible version of C<GIMME_V> which can only return
-C<G_SCALAR> or C<G_ARRAY>; in a void context, it returns C<G_SCALAR>.
-Deprecated. Use C<GIMME_V> instead.
+=back
- U32 GIMME
+=head1 Functions in file pp_pack.c
-=for hackers
-Found in file op.h
-=item GIMME_V
+=over 8
-The XSUB-writer's equivalent to Perl's C<wantarray>. Returns C<G_VOID>,
-C<G_SCALAR> or C<G_ARRAY> for void, scalar or list context,
-respectively.
+=item pack_cat
- U32 GIMME_V
+The engine implementing pack() Perl function.
+
+ void pack_cat(SV *cat, char *pat, char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags)
=for hackers
-Found in file op.h
+Found in file pp_pack.c
-=item grok_bin
+=item unpack_str
-converts a string representing a binary number to numeric form.
+The engine implementing unpack() Perl function.
-On entry I<start> and I<*len> give the string to scan, I<*flags> gives
-conversion flags, and I<result> should be NULL or a pointer to an NV.
-The scan stops at the end of the string, or the first invalid character.
-On return I<*len> is set to the length scanned string, and I<*flags> gives
-output flags.
+ I32 unpack_str(char *pat, char *patend, char *s, char *strbeg, char *strend, char **new_s, I32 ocnt, U32 flags)
-If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
-and nothing is written to I<*result>. If the value is > UV_MAX C<grok_bin>
-returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
-and writes the value to I<*result> (or the value is discarded if I<result>
-is NULL).
+=for hackers
+Found in file pp_pack.c
-The hex number may optionally be prefixed with "0b" or "b" unless
-C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
-C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the binary
-number may use '_' characters to separate digits.
- UV grok_bin(char* start, STRLEN* len, I32* flags, NV *result)
+=back
-=for hackers
-Found in file numeric.c
+=head1 Global Variables
-=item grok_hex
+=over 8
-converts a string representing a hex number to numeric form.
+=item PL_modglobal
-On entry I<start> and I<*len> give the string to scan, I<*flags> gives
-conversion flags, and I<result> should be NULL or a pointer to an NV.
-The scan stops at the end of the string, or the first non-hex-digit character.
-On return I<*len> is set to the length scanned string, and I<*flags> gives
-output flags.
+C<PL_modglobal> is a general purpose, interpreter global HV for use by
+extensions that need to keep information on a per-interpreter basis.
+In a pinch, it can also be used as a symbol table for extensions
+to share data among each other. It is a good idea to use keys
+prefixed by the package name of the extension that owns the data.
-If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
-and nothing is written to I<*result>. If the value is > UV_MAX C<grok_hex>
-returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
-and writes the value to I<*result> (or the value is discarded if I<result>
-is NULL).
+ HV* PL_modglobal
-The hex number may optionally be prefixed with "0x" or "x" unless
-C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
-C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the hex
-number may use '_' characters to separate digits.
+=for hackers
+Found in file intrpvar.h
- UV grok_hex(char* start, STRLEN* len, I32* flags, NV *result)
+=item PL_na
-=for hackers
-Found in file numeric.c
+A convenience variable which is typically used with C<SvPV> when one
+doesn't care about the length of the string. It is usually more efficient
+to either declare a local variable and use that instead or to use the
+C<SvPV_nolen> macro.
-=item grok_number
+ STRLEN PL_na
-Recognise (or not) a number. The type of the number is returned
-(0 if unrecognised), otherwise it is a bit-ORed combination of
-IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX, IS_NUMBER_NOT_INT,
-IS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUMBER_NAN (defined in perl.h).
+=for hackers
+Found in file thrdvar.h
-If the value of the number can fit an in UV, it is returned in the *valuep
-IS_NUMBER_IN_UV will be set to indicate that *valuep is valid, IS_NUMBER_IN_UV
-will never be set unless *valuep is valid, but *valuep may have been assigned
-to during processing even though IS_NUMBER_IN_UV is not set on return.
-If valuep is NULL, IS_NUMBER_IN_UV will be set for the same cases as when
-valuep is non-NULL, but no actual assignment (or SEGV) will occur.
+=item PL_sv_no
-IS_NUMBER_NOT_INT will be set with IS_NUMBER_IN_UV if trailing decimals were
-seen (in which case *valuep gives the true value truncated to an integer), and
-IS_NUMBER_NEG if the number is negative (in which case *valuep holds the
-absolute value). IS_NUMBER_IN_UV is not set if e notation was used or the
-number is larger than a UV.
+This is the C<false> SV. See C<PL_sv_yes>. Always refer to this as
+C<&PL_sv_no>.
- int grok_number(const char *pv, STRLEN len, UV *valuep)
+ SV PL_sv_no
=for hackers
-Found in file numeric.c
+Found in file intrpvar.h
-=item grok_numeric_radix
+=item PL_sv_undef
-Scan and skip for a numeric decimal separator (radix).
+This is the C<undef> SV. Always refer to this as C<&PL_sv_undef>.
- bool grok_numeric_radix(const char **sp, const char *send)
+ SV PL_sv_undef
=for hackers
-Found in file numeric.c
+Found in file intrpvar.h
-=item grok_oct
+=item PL_sv_yes
+This is the C<true> SV. See C<PL_sv_no>. Always refer to this as
+C<&PL_sv_yes>.
- UV grok_oct(char* start, STRLEN* len, I32* flags, NV *result)
+ SV PL_sv_yes
=for hackers
-Found in file numeric.c
+Found in file intrpvar.h
+
+
+=back
+
+=head1 GV Functions
+
+=over 8
=item GvSV
=for hackers
Found in file gv.c
+=item gv_fetchmeth_autoload
+
+Same as gv_fetchmeth(), but looks for autoloaded subroutines too.
+Returns a glob for the subroutine.
+
+For an autoloaded subroutine without a GV, will create a GV even
+if C<level < 0>. For an autoloaded subroutine without a stub, GvCV()
+of the result may be zero.
+
+ GV* gv_fetchmeth_autoload(HV* stash, const char* name, STRLEN len, I32 level)
+
+=for hackers
+Found in file gv.c
+
=item gv_stashpv
Returns a pointer to the stash for a specified package. C<name> should
=for hackers
Found in file gv.c
-=item G_ARRAY
-Used to indicate list context. See C<GIMME_V>, C<GIMME> and
-L<perlcall>.
+=back
-=for hackers
-Found in file cop.h
+=head1 Handy Values
-=item G_DISCARD
+=over 8
-Indicates that arguments returned from a callback should be discarded. See
-L<perlcall>.
+=item HEf_SVKEY
-=for hackers
-Found in file cop.h
+This flag, used in the length slot of hash entries and magic structures,
+specifies the structure contains an C<SV*> pointer where a C<char*> pointer
+is to be expected. (For information only--not to be used).
-=item G_EVAL
-Used to force a Perl C<eval> wrapper around a callback. See
-L<perlcall>.
+=for hackers
+Found in file hv.h
+=item Nullch
+
+Null character pointer.
=for hackers
-Found in file cop.h
+Found in file handy.h
-=item G_NOARGS
+=item Nullsv
-Indicates that no arguments are being sent to a callback. See
-L<perlcall>.
+Null SV pointer.
=for hackers
-Found in file cop.h
+Found in file handy.h
-=item G_SCALAR
-Used to indicate scalar context. See C<GIMME_V>, C<GIMME>, and
-L<perlcall>.
+=back
-=for hackers
-Found in file cop.h
+=head1 Hash Manipulation Functions
-=item G_VOID
+=over 8
-Used to indicate void context. See C<GIMME_V> and L<perlcall>.
+=item get_hv
-=for hackers
-Found in file cop.h
+Returns the HV of the specified Perl hash. If C<create> is set and the
+Perl variable does not exist then it will be created. If C<create> is not
+set and the variable does not exist then NULL is returned.
-=item HEf_SVKEY
+NOTE: the perl_ form of this function is deprecated.
-This flag, used in the length slot of hash entries and magic structures,
-specifies the structure contains a C<SV*> pointer where a C<char*> pointer
-is to be expected. (For information only--not to be used).
+ HV* get_hv(const char* name, I32 create)
=for hackers
-Found in file hv.h
+Found in file perl.c
=item HeHASH
Returns a boolean indicating whether the specified hash key exists. The
C<klen> is the length of the key.
- bool hv_exists(HV* tb, const char* key, I32 klen)
+ bool hv_exists(HV* tb, const char* key, I32 klen)
+
+=for hackers
+Found in file hv.c
+
+=item hv_exists_ent
+
+Returns a boolean indicating whether the specified hash key exists. C<hash>
+can be a valid precomputed hash value, or 0 to ask for it to be
+computed.
+
+ bool hv_exists_ent(HV* tb, SV* key, U32 hash)
+
+=for hackers
+Found in file hv.c
+
+=item hv_fetch
+
+Returns the SV which corresponds to the specified key in the hash. The
+C<klen> is the length of the key. If C<lval> is set then the fetch will be
+part of a store. Check that the return value is non-null before
+dereferencing it to an C<SV*>.
+
+See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
+information on how to use this function on tied hashes.
+
+ SV** hv_fetch(HV* tb, const char* key, I32 klen, I32 lval)
+
+=for hackers
+Found in file hv.c
+
+=item hv_fetch_ent
+
+Returns the hash entry which corresponds to the specified key in the hash.
+C<hash> must be a valid precomputed hash number for the given C<key>, or 0
+if you want the function to compute it. IF C<lval> is set then the fetch
+will be part of a store. Make sure the return value is non-null before
+accessing it. The return value when C<tb> is a tied hash is a pointer to a
+static location, so be sure to make a copy of the structure if you need to
+store it somewhere.
+
+See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
+information on how to use this function on tied hashes.
+
+ HE* hv_fetch_ent(HV* tb, SV* key, I32 lval, U32 hash)
+
+=for hackers
+Found in file hv.c
+
+=item hv_iterinit
+
+Prepares a starting point to traverse a hash table. Returns the number of
+keys in the hash (i.e. the same as C<HvKEYS(tb)>). The return value is
+currently only meaningful for hashes without tie magic.
+
+NOTE: Before version 5.004_65, C<hv_iterinit> used to return the number of
+hash buckets that happen to be in use. If you still need that esoteric
+value, you can get it through the macro C<HvFILL(tb)>.
+
+
+ I32 hv_iterinit(HV* tb)
+
+=for hackers
+Found in file hv.c
+
+=item hv_iterkey
+
+Returns the key from the current position of the hash iterator. See
+C<hv_iterinit>.
+
+ char* hv_iterkey(HE* entry, I32* retlen)
+
+=for hackers
+Found in file hv.c
+
+=item hv_iterkeysv
+
+Returns the key as an C<SV*> from the current position of the hash
+iterator. The return value will always be a mortal copy of the key. Also
+see C<hv_iterinit>.
+
+ SV* hv_iterkeysv(HE* entry)
+
+=for hackers
+Found in file hv.c
+
+=item hv_iternext
+
+Returns entries from a hash iterator. See C<hv_iterinit>.
+
+You may call C<hv_delete> or C<hv_delete_ent> on the hash entry that the
+iterator currently points to, without losing your place or invalidating your
+iterator. Note that in this case the current entry is deleted from the hash
+with your iterator holding the last reference to it. Your iterator is flagged
+to free the entry on the next call to C<hv_iternext>, so you must not discard
+your iterator immediately else the entry will leak - call C<hv_iternext> to
+trigger the resource deallocation.
+
+ HE* hv_iternext(HV* tb)
+
+=for hackers
+Found in file hv.c
+
+=item hv_iternextsv
+
+Performs an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one
+operation.
+
+ SV* hv_iternextsv(HV* hv, char** key, I32* retlen)
+
+=for hackers
+Found in file hv.c
+
+=item hv_iternext_flags
+
+Returns entries from a hash iterator. See C<hv_iterinit> and C<hv_iternext>.
+The C<flags> value will normally be zero; if HV_ITERNEXT_WANTPLACEHOLDERS is
+set the placeholders keys (for restricted hashes) will be returned in addition
+to normal keys. By default placeholders are automatically skipped over.
+Currently a placeholder is implemented with a value that is literally
+<&Perl_sv_undef> (a regular C<undef> value is a normal read-write SV for which
+C<!SvOK> is false). Note that the implementation of placeholders and
+restricted hashes may change, and the implementation currently is
+insufficiently abstracted for any change to be tidy.
+
+NOTE: this function is experimental and may change or be
+removed without notice.
+
+ HE* hv_iternext_flags(HV* tb, I32 flags)
+
+=for hackers
+Found in file hv.c
+
+=item hv_iterval
+
+Returns the value from the current position of the hash iterator. See
+C<hv_iterkey>.
+
+ SV* hv_iterval(HV* tb, HE* entry)
+
+=for hackers
+Found in file hv.c
+
+=item hv_magic
+
+Adds magic to a hash. See C<sv_magic>.
+
+ void hv_magic(HV* hv, GV* gv, int how)
+
+=for hackers
+Found in file hv.c
+
+=item hv_store
+
+Stores an SV in a hash. The hash key is specified as C<key> and C<klen> is
+the length of the key. The C<hash> parameter is the precomputed hash
+value; if it is zero then Perl will compute it. The return value will be
+NULL if the operation failed or if the value did not need to be actually
+stored within the hash (as in the case of tied hashes). Otherwise it can
+be dereferenced to get the original C<SV*>. Note that the caller is
+responsible for suitably incrementing the reference count of C<val> before
+the call, and decrementing it if the function returned NULL.
+
+See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
+information on how to use this function on tied hashes.
+
+ SV** hv_store(HV* tb, const char* key, I32 klen, SV* val, U32 hash)
+
+=for hackers
+Found in file hv.c
+
+=item hv_store_ent
+
+Stores C<val> in a hash. The hash key is specified as C<key>. The C<hash>
+parameter is the precomputed hash value; if it is zero then Perl will
+compute it. The return value is the new hash entry so created. It will be
+NULL if the operation failed or if the value did not need to be actually
+stored within the hash (as in the case of tied hashes). Otherwise the
+contents of the return value can be accessed using the C<He?> macros
+described here. Note that the caller is responsible for suitably
+incrementing the reference count of C<val> before the call, and
+decrementing it if the function returned NULL.
+
+See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
+information on how to use this function on tied hashes.
+
+ HE* hv_store_ent(HV* tb, SV* key, SV* val, U32 hash)
+
+=for hackers
+Found in file hv.c
+
+=item hv_undef
+
+Undefines the hash.
+
+ void hv_undef(HV* tb)
+
+=for hackers
+Found in file hv.c
+
+=item newHV
+
+Creates a new HV. The reference count is set to 1.
+
+ HV* newHV()
+
+=for hackers
+Found in file hv.c
+
+=item Nullhv
+
+Null HV pointer.
+
+
+=for hackers
+Found in file hv.h
+
+
+=back
+
+=head1 Magical Functions
+
+=over 8
+
+=item mg_clear
+
+Clear something magical that the SV represents. See C<sv_magic>.
+
+ int mg_clear(SV* sv)
+
+=for hackers
+Found in file mg.c
+
+=item mg_copy
+
+Copies the magic from one SV to another. See C<sv_magic>.
+
+ int mg_copy(SV* sv, SV* nsv, const char* key, I32 klen)
+
+=for hackers
+Found in file mg.c
+
+=item mg_find
+
+Finds the magic pointer for type matching the SV. See C<sv_magic>.
+
+ MAGIC* mg_find(SV* sv, int type)
+
+=for hackers
+Found in file mg.c
+
+=item mg_free
+
+Free any magic storage used by the SV. See C<sv_magic>.
+
+ int mg_free(SV* sv)
=for hackers
-Found in file hv.c
+Found in file mg.c
-=item hv_exists_ent
+=item mg_get
-Returns a boolean indicating whether the specified hash key exists. C<hash>
-can be a valid precomputed hash value, or 0 to ask for it to be
-computed.
+Do magic after a value is retrieved from the SV. See C<sv_magic>.
- bool hv_exists_ent(HV* tb, SV* key, U32 hash)
+ int mg_get(SV* sv)
=for hackers
-Found in file hv.c
-
-=item hv_fetch
+Found in file mg.c
-Returns the SV which corresponds to the specified key in the hash. The
-C<klen> is the length of the key. If C<lval> is set then the fetch will be
-part of a store. Check that the return value is non-null before
-dereferencing it to a C<SV*>.
+=item mg_length
-See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
-information on how to use this function on tied hashes.
+Report on the SV's length. See C<sv_magic>.
- SV** hv_fetch(HV* tb, const char* key, I32 klen, I32 lval)
+ U32 mg_length(SV* sv)
=for hackers
-Found in file hv.c
-
-=item hv_fetch_ent
+Found in file mg.c
-Returns the hash entry which corresponds to the specified key in the hash.
-C<hash> must be a valid precomputed hash number for the given C<key>, or 0
-if you want the function to compute it. IF C<lval> is set then the fetch
-will be part of a store. Make sure the return value is non-null before
-accessing it. The return value when C<tb> is a tied hash is a pointer to a
-static location, so be sure to make a copy of the structure if you need to
-store it somewhere.
+=item mg_magical
-See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
-information on how to use this function on tied hashes.
+Turns on the magical status of an SV. See C<sv_magic>.
- HE* hv_fetch_ent(HV* tb, SV* key, I32 lval, U32 hash)
+ void mg_magical(SV* sv)
=for hackers
-Found in file hv.c
-
-=item hv_iterinit
+Found in file mg.c
-Prepares a starting point to traverse a hash table. Returns the number of
-keys in the hash (i.e. the same as C<HvKEYS(tb)>). The return value is
-currently only meaningful for hashes without tie magic.
+=item mg_set
-NOTE: Before version 5.004_65, C<hv_iterinit> used to return the number of
-hash buckets that happen to be in use. If you still need that esoteric
-value, you can get it through the macro C<HvFILL(tb)>.
+Do magic after a value is assigned to the SV. See C<sv_magic>.
- I32 hv_iterinit(HV* tb)
+ int mg_set(SV* sv)
=for hackers
-Found in file hv.c
+Found in file mg.c
-=item hv_iterkey
+=item SvGETMAGIC
-Returns the key from the current position of the hash iterator. See
-C<hv_iterinit>.
+Invokes C<mg_get> on an SV if it has 'get' magic. This macro evaluates its
+argument more than once.
- char* hv_iterkey(HE* entry, I32* retlen)
+ void SvGETMAGIC(SV* sv)
=for hackers
-Found in file hv.c
+Found in file sv.h
-=item hv_iterkeysv
+=item SvLOCK
-Returns the key as an C<SV*> from the current position of the hash
-iterator. The return value will always be a mortal copy of the key. Also
-see C<hv_iterinit>.
+Arranges for a mutual exclusion lock to be obtained on sv if a suitable module
+has been loaded.
- SV* hv_iterkeysv(HE* entry)
+ void SvLOCK(SV* sv)
=for hackers
-Found in file hv.c
+Found in file sv.h
-=item hv_iternext
+=item SvSETMAGIC
-Returns entries from a hash iterator. See C<hv_iterinit>.
+Invokes C<mg_set> on an SV if it has 'set' magic. This macro evaluates its
+argument more than once.
- HE* hv_iternext(HV* tb)
+ void SvSETMAGIC(SV* sv)
=for hackers
-Found in file hv.c
+Found in file sv.h
-=item hv_iternextsv
+=item SvSetMagicSV
-Performs an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one
-operation.
+Like C<SvSetSV>, but does any set magic required afterwards.
- SV* hv_iternextsv(HV* hv, char** key, I32* retlen)
+ void SvSetMagicSV(SV* dsb, SV* ssv)
=for hackers
-Found in file hv.c
+Found in file sv.h
-=item hv_iterval
+=item SvSetMagicSV_nosteal
-Returns the value from the current position of the hash iterator. See
-C<hv_iterkey>.
+Like C<SvSetMagicSV>, but does any set magic required afterwards.
- SV* hv_iterval(HV* tb, HE* entry)
+ void SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
=for hackers
-Found in file hv.c
+Found in file sv.h
-=item hv_magic
+=item SvSetSV
-Adds magic to a hash. See C<sv_magic>.
+Calls C<sv_setsv> if dsv is not the same as ssv. May evaluate arguments
+more than once.
- void hv_magic(HV* hv, GV* gv, int how)
+ void SvSetSV(SV* dsb, SV* ssv)
=for hackers
-Found in file hv.c
-
-=item hv_store
+Found in file sv.h
-Stores an SV in a hash. The hash key is specified as C<key> and C<klen> is
-the length of the key. The C<hash> parameter is the precomputed hash
-value; if it is zero then Perl will compute it. The return value will be
-NULL if the operation failed or if the value did not need to be actually
-stored within the hash (as in the case of tied hashes). Otherwise it can
-be dereferenced to get the original C<SV*>. Note that the caller is
-responsible for suitably incrementing the reference count of C<val> before
-the call, and decrementing it if the function returned NULL.
+=item SvSetSV_nosteal
-See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
-information on how to use this function on tied hashes.
+Calls a non-destructive version of C<sv_setsv> if dsv is not the same as
+ssv. May evaluate arguments more than once.
- SV** hv_store(HV* tb, const char* key, I32 klen, SV* val, U32 hash)
+ void SvSetSV_nosteal(SV* dsv, SV* ssv)
=for hackers
-Found in file hv.c
-
-=item hv_store_ent
+Found in file sv.h
-Stores C<val> in a hash. The hash key is specified as C<key>. The C<hash>
-parameter is the precomputed hash value; if it is zero then Perl will
-compute it. The return value is the new hash entry so created. It will be
-NULL if the operation failed or if the value did not need to be actually
-stored within the hash (as in the case of tied hashes). Otherwise the
-contents of the return value can be accessed using the C<He?> macros
-described here. Note that the caller is responsible for suitably
-incrementing the reference count of C<val> before the call, and
-decrementing it if the function returned NULL.
+=item SvSHARE
-See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
-information on how to use this function on tied hashes.
+Arranges for sv to be shared between threads if a suitable module
+has been loaded.
- HE* hv_store_ent(HV* tb, SV* key, SV* val, U32 hash)
+ void SvSHARE(SV* sv)
=for hackers
-Found in file hv.c
+Found in file sv.h
-=item hv_undef
-Undefines the hash.
+=back
- void hv_undef(HV* tb)
+=head1 Memory Management
-=for hackers
-Found in file hv.c
+=over 8
-=item isALNUM
+=item Copy
-Returns a boolean indicating whether the C C<char> is an ASCII alphanumeric
-character (including underscore) or digit.
+The XSUB-writer's interface to the C C<memcpy> function. The C<src> is the
+source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
+the type. May fail on overlapping copies. See also C<Move>.
- bool isALNUM(char ch)
+ void Copy(void* src, void* dest, int nitems, type)
=for hackers
Found in file handy.h
-=item isALPHA
+=item Move
-Returns a boolean indicating whether the C C<char> is an ASCII alphabetic
-character.
+The XSUB-writer's interface to the C C<memmove> function. The C<src> is the
+source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
+the type. Can do overlapping moves. See also C<Copy>.
- bool isALPHA(char ch)
+ void Move(void* src, void* dest, int nitems, type)
=for hackers
Found in file handy.h
-=item isDIGIT
+=item New
-Returns a boolean indicating whether the C C<char> is an ASCII
-digit.
+The XSUB-writer's interface to the C C<malloc> function.
- bool isDIGIT(char ch)
+ void New(int id, void* ptr, int nitems, type)
=for hackers
Found in file handy.h
-=item isLOWER
+=item Newc
-Returns a boolean indicating whether the C C<char> is a lowercase
-character.
+The XSUB-writer's interface to the C C<malloc> function, with
+cast.
- bool isLOWER(char ch)
+ void Newc(int id, void* ptr, int nitems, type, cast)
=for hackers
Found in file handy.h
-=item isSPACE
+=item NEWSV
-Returns a boolean indicating whether the C C<char> is whitespace.
+Creates a new SV. A non-zero C<len> parameter indicates the number of
+bytes of preallocated string space the SV should have. An extra byte for a
+tailing NUL is also reserved. (SvPOK is not set for the SV even if string
+space is allocated.) The reference count for the new SV is set to 1.
+C<id> is an integer id between 0 and 1299 (used to identify leaks).
- bool isSPACE(char ch)
+
+ SV* NEWSV(int id, STRLEN len)
=for hackers
Found in file handy.h
-=item isUPPER
+=item Newz
-Returns a boolean indicating whether the C C<char> is an uppercase
-character.
+The XSUB-writer's interface to the C C<malloc> function. The allocated
+memory is zeroed with C<memzero>.
- bool isUPPER(char ch)
+ void Newz(int id, void* ptr, int nitems, type)
=for hackers
Found in file handy.h
-=item is_utf8_char
+=item Poison
-Tests if some arbitrary number of bytes begins in a valid UTF-8
-character. Note that an INVARIANT (i.e. ASCII) character is a valid UTF-8 character.
-The actual number of bytes in the UTF-8 character will be returned if
-it is valid, otherwise 0.
+Fill up memory with a pattern (byte 0xAB over and over again) that
+hopefully catches attempts to access uninitialized memory.
- STRLEN is_utf8_char(U8 *p)
+ void Poison(void* dest, int nitems, type)
=for hackers
-Found in file utf8.c
+Found in file handy.h
-=item is_utf8_string
+=item Renew
-Returns true if first C<len> bytes of the given string form a valid UTF8
-string, false otherwise. Note that 'a valid UTF8 string' does not mean
-'a string that contains UTF8' because a valid ASCII string is a valid
-UTF8 string.
+The XSUB-writer's interface to the C C<realloc> function.
- bool is_utf8_string(U8 *s, STRLEN len)
+ void Renew(void* ptr, int nitems, type)
=for hackers
-Found in file utf8.c
+Found in file handy.h
-=item items
+=item Renewc
-Variable which is setup by C<xsubpp> to indicate the number of
-items on the stack. See L<perlxs/"Variable-length Parameter Lists">.
+The XSUB-writer's interface to the C C<realloc> function, with
+cast.
- I32 items
+ void Renewc(void* ptr, int nitems, type, cast)
=for hackers
-Found in file XSUB.h
+Found in file handy.h
-=item ix
+=item Safefree
-Variable which is setup by C<xsubpp> to indicate which of an
-XSUB's aliases was used to invoke it. See L<perlxs/"The ALIAS: Keyword">.
+The XSUB-writer's interface to the C C<free> function.
- I32 ix
+ void Safefree(void* ptr)
=for hackers
-Found in file XSUB.h
+Found in file handy.h
-=item LEAVE
+=item savepv
-Closing bracket on a callback. See C<ENTER> and L<perlcall>.
+Perl's version of C<strdup()>. Returns a pointer to a newly allocated
+string which is a duplicate of C<pv>. The size of the string is
+determined by C<strlen()>. The memory allocated for the new string can
+be freed with the C<Safefree()> function.
- LEAVE;
+ char* savepv(const char* pv)
=for hackers
-Found in file scope.h
+Found in file util.c
-=item load_module
+=item savepvn
-Loads the module whose name is pointed to by the string part of name.
-Note that the actual module name, not its filename, should be given.
-Eg, "Foo::Bar" instead of "Foo/Bar.pm". flags can be any of
-PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT, or PERL_LOADMOD_IMPORT_OPS
-(or 0 for no flags). ver, if specified, provides version semantics
-similar to C<use Foo::Bar VERSION>. The optional trailing SV*
-arguments can be used to specify arguments to the module's import()
-method, similar to C<use Foo::Bar VERSION LIST>.
+Perl's version of what C<strndup()> would be if it existed. Returns a
+pointer to a newly allocated string which is a duplicate of the first
+C<len> bytes from C<pv>. The memory allocated for the new string can be
+freed with the C<Safefree()> function.
- void load_module(U32 flags, SV* name, SV* ver, ...)
+ char* savepvn(const char* pv, I32 len)
=for hackers
-Found in file op.c
+Found in file util.c
-=item looks_like_number
+=item savesharedpv
-Test if the content of an SV looks like a number (or is a number).
-C<Inf> and C<Infinity> are treated as numbers (so will not issue a
-non-numeric warning), even if your atof() doesn't grok them.
+A version of C<savepv()> which allocates the duplicate string in memory
+which is shared between threads.
- I32 looks_like_number(SV* sv)
+ char* savesharedpv(const char* pv)
=for hackers
-Found in file sv.c
+Found in file util.c
-=item MARK
+=item StructCopy
-Stack marker variable for the XSUB. See C<dMARK>.
+This is an architecture-independent macro to copy one structure to another.
+
+ void StructCopy(type src, type dest, type)
=for hackers
-Found in file pp.h
+Found in file handy.h
-=item mg_clear
+=item Zero
-Clear something magical that the SV represents. See C<sv_magic>.
+The XSUB-writer's interface to the C C<memzero> function. The C<dest> is the
+destination, C<nitems> is the number of items, and C<type> is the type.
- int mg_clear(SV* sv)
+ void Zero(void* dest, int nitems, type)
=for hackers
-Found in file mg.c
+Found in file handy.h
-=item mg_copy
-Copies the magic from one SV to another. See C<sv_magic>.
+=back
- int mg_copy(SV* sv, SV* nsv, const char* key, I32 klen)
+=head1 Miscellaneous Functions
-=for hackers
-Found in file mg.c
+=over 8
-=item mg_find
+=item fbm_compile
-Finds the magic pointer for type matching the SV. See C<sv_magic>.
+Analyses the string in order to make fast searches on it using fbm_instr()
+-- the Boyer-Moore algorithm.
- MAGIC* mg_find(SV* sv, int type)
+ void fbm_compile(SV* sv, U32 flags)
=for hackers
-Found in file mg.c
+Found in file util.c
-=item mg_free
+=item fbm_instr
-Free any magic storage used by the SV. See C<sv_magic>.
+Returns the location of the SV in the string delimited by C<str> and
+C<strend>. It returns C<Nullch> if the string can't be found. The C<sv>
+does not have to be fbm_compiled, but the search will not be as fast
+then.
- int mg_free(SV* sv)
+ char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags)
=for hackers
-Found in file mg.c
+Found in file util.c
-=item mg_get
+=item form
-Do magic after a value is retrieved from the SV. See C<sv_magic>.
+Takes a sprintf-style format pattern and conventional
+(non-SV) arguments and returns the formatted string.
- int mg_get(SV* sv)
+ (char *) Perl_form(pTHX_ const char* pat, ...)
-=for hackers
-Found in file mg.c
+can be used any place a string (char *) is required:
-=item mg_length
+ char * s = Perl_form("%d.%d",major,minor);
-Report on the SV's length. See C<sv_magic>.
+Uses a single private buffer so if you want to format several strings you
+must explicitly copy the earlier strings away (and free the copies when you
+are done).
- U32 mg_length(SV* sv)
+ char* form(const char* pat, ...)
=for hackers
-Found in file mg.c
+Found in file util.c
-=item mg_magical
+=item getcwd_sv
-Turns on the magical status of an SV. See C<sv_magic>.
+Fill the sv with current working directory
- void mg_magical(SV* sv)
+ int getcwd_sv(SV* sv)
=for hackers
-Found in file mg.c
+Found in file util.c
-=item mg_set
+=item strEQ
-Do magic after a value is assigned to the SV. See C<sv_magic>.
+Test two strings to see if they are equal. Returns true or false.
- int mg_set(SV* sv)
+ bool strEQ(char* s1, char* s2)
=for hackers
-Found in file mg.c
+Found in file handy.h
-=item Move
+=item strGE
-The XSUB-writer's interface to the C C<memmove> function. The C<src> is the
-source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
-the type. Can do overlapping moves. See also C<Copy>.
+Test two strings to see if the first, C<s1>, is greater than or equal to
+the second, C<s2>. Returns true or false.
- void Move(void* src, void* dest, int nitems, type)
+ bool strGE(char* s1, char* s2)
=for hackers
Found in file handy.h
-=item New
+=item strGT
-The XSUB-writer's interface to the C C<malloc> function.
+Test two strings to see if the first, C<s1>, is greater than the second,
+C<s2>. Returns true or false.
- void New(int id, void* ptr, int nitems, type)
+ bool strGT(char* s1, char* s2)
=for hackers
Found in file handy.h
-=item newAV
+=item strLE
-Creates a new AV. The reference count is set to 1.
+Test two strings to see if the first, C<s1>, is less than or equal to the
+second, C<s2>. Returns true or false.
- AV* newAV()
+ bool strLE(char* s1, char* s2)
=for hackers
-Found in file av.c
+Found in file handy.h
-=item Newc
+=item strLT
-The XSUB-writer's interface to the C C<malloc> function, with
-cast.
+Test two strings to see if the first, C<s1>, is less than the second,
+C<s2>. Returns true or false.
- void Newc(int id, void* ptr, int nitems, type, cast)
+ bool strLT(char* s1, char* s2)
=for hackers
Found in file handy.h
-=item newCONSTSUB
+=item strNE
-Creates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is
-eligible for inlining at compile-time.
+Test two strings to see if they are different. Returns true or
+false.
- CV* newCONSTSUB(HV* stash, char* name, SV* sv)
+ bool strNE(char* s1, char* s2)
=for hackers
-Found in file op.c
+Found in file handy.h
-=item newHV
+=item strnEQ
-Creates a new HV. The reference count is set to 1.
+Test two strings to see if they are equal. The C<len> parameter indicates
+the number of bytes to compare. Returns true or false. (A wrapper for
+C<strncmp>).
- HV* newHV()
+ bool strnEQ(char* s1, char* s2, STRLEN len)
=for hackers
-Found in file hv.c
+Found in file handy.h
-=item newRV_inc
+=item strnNE
-Creates an RV wrapper for an SV. The reference count for the original SV is
-incremented.
+Test two strings to see if they are different. The C<len> parameter
+indicates the number of bytes to compare. Returns true or false. (A
+wrapper for C<strncmp>).
- SV* newRV_inc(SV* sv)
+ bool strnNE(char* s1, char* s2, STRLEN len)
=for hackers
-Found in file sv.h
+Found in file handy.h
-=item newRV_noinc
-Creates an RV wrapper for an SV. The reference count for the original
-SV is B<not> incremented.
+=back
- SV* newRV_noinc(SV *sv)
+=head1 Numeric functions
-=for hackers
-Found in file sv.c
+=over 8
-=item NEWSV
+=item grok_bin
-Creates a new SV. A non-zero C<len> parameter indicates the number of
-bytes of preallocated string space the SV should have. An extra byte for a
-tailing NUL is also reserved. (SvPOK is not set for the SV even if string
-space is allocated.) The reference count for the new SV is set to 1.
-C<id> is an integer id between 0 and 1299 (used to identify leaks).
+converts a string representing a binary number to numeric form.
- SV* NEWSV(int id, STRLEN len)
+On entry I<start> and I<*len> give the string to scan, I<*flags> gives
+conversion flags, and I<result> should be NULL or a pointer to an NV.
+The scan stops at the end of the string, or the first invalid character.
+On return I<*len> is set to the length scanned string, and I<*flags> gives
+output flags.
+
+If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
+and nothing is written to I<*result>. If the value is > UV_MAX C<grok_bin>
+returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
+and writes the value to I<*result> (or the value is discarded if I<result>
+is NULL).
+
+The hex number may optionally be prefixed with "0b" or "b" unless
+C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
+C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the binary
+number may use '_' characters to separate digits.
+
+ UV grok_bin(char* start, STRLEN* len, I32* flags, NV *result)
=for hackers
-Found in file handy.h
+Found in file numeric.c
-=item newSV
+=item grok_hex
-Create a new null SV, or if len > 0, create a new empty SVt_PV type SV
-with an initial PV allocation of len+1. Normally accessed via the C<NEWSV>
-macro.
+converts a string representing a hex number to numeric form.
- SV* newSV(STRLEN len)
+On entry I<start> and I<*len> give the string to scan, I<*flags> gives
+conversion flags, and I<result> should be NULL or a pointer to an NV.
+The scan stops at the end of the string, or the first non-hex-digit character.
+On return I<*len> is set to the length scanned string, and I<*flags> gives
+output flags.
+
+If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
+and nothing is written to I<*result>. If the value is > UV_MAX C<grok_hex>
+returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
+and writes the value to I<*result> (or the value is discarded if I<result>
+is NULL).
+
+The hex number may optionally be prefixed with "0x" or "x" unless
+C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
+C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the hex
+number may use '_' characters to separate digits.
+
+ UV grok_hex(char* start, STRLEN* len, I32* flags, NV *result)
=for hackers
-Found in file sv.c
+Found in file numeric.c
-=item newSViv
+=item grok_number
-Creates a new SV and copies an integer into it. The reference count for the
-SV is set to 1.
+Recognise (or not) a number. The type of the number is returned
+(0 if unrecognised), otherwise it is a bit-ORed combination of
+IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX, IS_NUMBER_NOT_INT,
+IS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUMBER_NAN (defined in perl.h).
- SV* newSViv(IV i)
+If the value of the number can fit an in UV, it is returned in the *valuep
+IS_NUMBER_IN_UV will be set to indicate that *valuep is valid, IS_NUMBER_IN_UV
+will never be set unless *valuep is valid, but *valuep may have been assigned
+to during processing even though IS_NUMBER_IN_UV is not set on return.
+If valuep is NULL, IS_NUMBER_IN_UV will be set for the same cases as when
+valuep is non-NULL, but no actual assignment (or SEGV) will occur.
+
+IS_NUMBER_NOT_INT will be set with IS_NUMBER_IN_UV if trailing decimals were
+seen (in which case *valuep gives the true value truncated to an integer), and
+IS_NUMBER_NEG if the number is negative (in which case *valuep holds the
+absolute value). IS_NUMBER_IN_UV is not set if e notation was used or the
+number is larger than a UV.
+
+ int grok_number(const char *pv, STRLEN len, UV *valuep)
=for hackers
-Found in file sv.c
+Found in file numeric.c
-=item newSVnv
+=item grok_numeric_radix
-Creates a new SV and copies a floating point value into it.
-The reference count for the SV is set to 1.
+Scan and skip for a numeric decimal separator (radix).
- SV* newSVnv(NV n)
+ bool grok_numeric_radix(const char **sp, const char *send)
=for hackers
-Found in file sv.c
+Found in file numeric.c
-=item newSVpv
+=item grok_oct
-Creates a new SV and copies a string into it. The reference count for the
-SV is set to 1. If C<len> is zero, Perl will compute the length using
-strlen(). For efficiency, consider using C<newSVpvn> instead.
- SV* newSVpv(const char* s, STRLEN len)
+ UV grok_oct(char* start, STRLEN* len, I32* flags, NV *result)
=for hackers
-Found in file sv.c
-
-=item newSVpvf
+Found in file numeric.c
-Creates a new SV and initializes it with the string formatted like
-C<sprintf>.
+=item scan_bin
- SV* newSVpvf(const char* pat, ...)
+For backwards compatibility. Use C<grok_bin> instead.
+
+ NV scan_bin(char* start, STRLEN len, STRLEN* retlen)
=for hackers
-Found in file sv.c
+Found in file numeric.c
-=item newSVpvn
+=item scan_hex
-Creates a new SV and copies a string into it. The reference count for the
-SV is set to 1. Note that if C<len> is zero, Perl will create a zero length
-string. You are responsible for ensuring that the source string is at least
-C<len> bytes long.
+For backwards compatibility. Use C<grok_hex> instead.
- SV* newSVpvn(const char* s, STRLEN len)
+ NV scan_hex(char* start, STRLEN len, STRLEN* retlen)
=for hackers
-Found in file sv.c
+Found in file numeric.c
-=item newSVpvn_share
+=item scan_oct
-Creates a new SV with its SvPVX pointing to a shared string in the string
-table. If the string does not already exist in the table, it is created
-first. Turns on READONLY and FAKE. The string's hash is stored in the UV
-slot of the SV; if the C<hash> parameter is non-zero, that value is used;
-otherwise the hash is computed. The idea here is that as the string table
-is used for shared hash keys these strings will have SvPVX == HeKEY and
-hash lookup will avoid string compare.
+For backwards compatibility. Use C<grok_oct> instead.
- SV* newSVpvn_share(const char* s, I32 len, U32 hash)
+ NV scan_oct(char* start, STRLEN len, STRLEN* retlen)
=for hackers
-Found in file sv.c
+Found in file numeric.c
-=item newSVrv
-Creates a new SV for the RV, C<rv>, to point to. If C<rv> is not an RV then
-it will be upgraded to one. If C<classname> is non-null then the new SV will
-be blessed in the specified package. The new SV is returned and its
-reference count is 1.
+=back
- SV* newSVrv(SV* rv, const char* classname)
+=head1 Optree Manipulation Functions
-=for hackers
-Found in file sv.c
+=over 8
-=item newSVsv
+=item cv_const_sv
-Creates a new SV which is an exact duplicate of the original SV.
-(Uses C<sv_setsv>).
+If C<cv> is a constant sub eligible for inlining. returns the constant
+value returned by the sub. Otherwise, returns NULL.
- SV* newSVsv(SV* old)
+Constant subs can be created with C<newCONSTSUB> or as described in
+L<perlsub/"Constant Functions">.
+
+ SV* cv_const_sv(CV* cv)
=for hackers
-Found in file sv.c
+Found in file op.c
-=item newSVuv
+=item newCONSTSUB
-Creates a new SV and copies an unsigned integer into it.
-The reference count for the SV is set to 1.
+Creates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is
+eligible for inlining at compile-time.
- SV* newSVuv(UV u)
+ CV* newCONSTSUB(HV* stash, char* name, SV* sv)
=for hackers
-Found in file sv.c
+Found in file op.c
=item newXS
=for hackers
Found in file op.c
-=item newXSproto
-Used by C<xsubpp> to hook up XSUBs as Perl subs. Adds Perl prototypes to
-the subs.
+=back
+
+=head1 Stack Manipulation Macros
+
+=over 8
+
+=item dMARK
+
+Declare a stack marker variable, C<mark>, for the XSUB. See C<MARK> and
+C<dORIGMARK>.
+
+ dMARK;
=for hackers
-Found in file XSUB.h
+Found in file pp.h
-=item Newz
+=item dORIGMARK
-The XSUB-writer's interface to the C C<malloc> function. The allocated
-memory is zeroed with C<memzero>.
+Saves the original stack mark for the XSUB. See C<ORIGMARK>.
- void Newz(int id, void* ptr, int nitems, type)
+ dORIGMARK;
=for hackers
-Found in file handy.h
+Found in file pp.h
-=item Nullav
+=item dSP
-Null AV pointer.
+Declares a local copy of perl's stack pointer for the XSUB, available via
+the C<SP> macro. See C<SP>.
+
+ dSP;
=for hackers
-Found in file av.h
+Found in file pp.h
-=item Nullch
+=item EXTEND
-Null character pointer.
+Used to extend the argument stack for an XSUB's return values. Once
+used, guarantees that there is room for at least C<nitems> to be pushed
+onto the stack.
+
+ void EXTEND(SP, int nitems)
=for hackers
-Found in file handy.h
+Found in file pp.h
-=item Nullcv
+=item MARK
-Null CV pointer.
+Stack marker variable for the XSUB. See C<dMARK>.
=for hackers
-Found in file cv.h
+Found in file pp.h
-=item Nullhv
+=item ORIGMARK
-Null HV pointer.
+The original stack mark for the XSUB. See C<dORIGMARK>.
=for hackers
-Found in file hv.h
+Found in file pp.h
-=item Nullsv
+=item POPi
-Null SV pointer.
+Pops an integer off the stack.
+
+ IV POPi
=for hackers
-Found in file handy.h
+Found in file pp.h
-=item ORIGMARK
+=item POPl
-The original stack mark for the XSUB. See C<dORIGMARK>.
+Pops a long off the stack.
+
+ long POPl
=for hackers
Found in file pp.h
-=item perl_alloc
+=item POPn
-Allocates a new Perl interpreter. See L<perlembed>.
+Pops a double off the stack.
- PerlInterpreter* perl_alloc()
+ NV POPn
=for hackers
-Found in file perl.c
+Found in file pp.h
-=item perl_clone
+=item POPp
-Create and return a new interpreter by cloning the current one.
+Pops a string off the stack. Deprecated. New code should provide
+a STRLEN n_a and use POPpx.
- PerlInterpreter* perl_clone(PerlInterpreter* interp, UV flags)
+ char* POPp
=for hackers
-Found in file sv.c
+Found in file pp.h
-=item perl_construct
+=item POPpbytex
-Initializes a new Perl interpreter. See L<perlembed>.
+Pops a string off the stack which must consist of bytes i.e. characters < 256.
+Requires a variable STRLEN n_a in scope.
- void perl_construct(PerlInterpreter* interp)
+ char* POPpbytex
=for hackers
-Found in file perl.c
+Found in file pp.h
-=item perl_destruct
+=item POPpx
-Shuts down a Perl interpreter. See L<perlembed>.
+Pops a string off the stack.
+Requires a variable STRLEN n_a in scope.
- int perl_destruct(PerlInterpreter* interp)
+ char* POPpx
=for hackers
-Found in file perl.c
+Found in file pp.h
-=item perl_free
+=item POPs
-Releases a Perl interpreter. See L<perlembed>.
+Pops an SV off the stack.
- void perl_free(PerlInterpreter* interp)
+ SV* POPs
=for hackers
-Found in file perl.c
+Found in file pp.h
-=item perl_parse
+=item PUSHi
-Tells a Perl interpreter to parse a Perl script. See L<perlembed>.
+Push an integer onto the stack. The stack must have room for this element.
+Handles 'set' magic. See C<XPUSHi>.
- int perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env)
+ void PUSHi(IV iv)
=for hackers
-Found in file perl.c
+Found in file pp.h
-=item perl_run
+=item PUSHMARK
-Tells a Perl interpreter to run. See L<perlembed>.
+Opening bracket for arguments on a callback. See C<PUTBACK> and
+L<perlcall>.
- int perl_run(PerlInterpreter* interp)
+ PUSHMARK;
=for hackers
-Found in file perl.c
+Found in file pp.h
-=item PL_modglobal
+=item PUSHn
-C<PL_modglobal> is a general purpose, interpreter global HV for use by
-extensions that need to keep information on a per-interpreter basis.
-In a pinch, it can also be used as a symbol table for extensions
-to share data among each other. It is a good idea to use keys
-prefixed by the package name of the extension that owns the data.
+Push a double onto the stack. The stack must have room for this element.
+Handles 'set' magic. See C<XPUSHn>.
- HV* PL_modglobal
+ void PUSHn(NV nv)
=for hackers
-Found in file intrpvar.h
+Found in file pp.h
-=item PL_na
+=item PUSHp
-A convenience variable which is typically used with C<SvPV> when one
-doesn't care about the length of the string. It is usually more efficient
-to either declare a local variable and use that instead or to use the
-C<SvPV_nolen> macro.
+Push a string onto the stack. The stack must have room for this element.
+The C<len> indicates the length of the string. Handles 'set' magic. See
+C<XPUSHp>.
- STRLEN PL_na
+ void PUSHp(char* str, STRLEN len)
=for hackers
-Found in file thrdvar.h
+Found in file pp.h
-=item PL_sv_no
+=item PUSHs
-This is the C<false> SV. See C<PL_sv_yes>. Always refer to this as
-C<&PL_sv_no>.
+Push an SV onto the stack. The stack must have room for this element.
+Does not handle 'set' magic. See C<XPUSHs>.
- SV PL_sv_no
+ void PUSHs(SV* sv)
=for hackers
-Found in file intrpvar.h
+Found in file pp.h
-=item PL_sv_undef
+=item PUSHu
-This is the C<undef> SV. Always refer to this as C<&PL_sv_undef>.
+Push an unsigned integer onto the stack. The stack must have room for this
+element. See C<XPUSHu>.
- SV PL_sv_undef
+ void PUSHu(UV uv)
=for hackers
-Found in file intrpvar.h
+Found in file pp.h
-=item PL_sv_yes
+=item PUTBACK
-This is the C<true> SV. See C<PL_sv_no>. Always refer to this as
-C<&PL_sv_yes>.
+Closing bracket for XSUB arguments. This is usually handled by C<xsubpp>.
+See C<PUSHMARK> and L<perlcall> for other uses.
- SV PL_sv_yes
+ PUTBACK;
=for hackers
-Found in file intrpvar.h
+Found in file pp.h
+
+=item SP
+
+Stack pointer. This is usually handled by C<xsubpp>. See C<dSP> and
+C<SPAGAIN>.
+
+=for hackers
+Found in file pp.h
-=item POPi
+=item SPAGAIN
-Pops an integer off the stack.
+Refetch the stack pointer. Used after a callback. See L<perlcall>.
- IV POPi
+ SPAGAIN;
=for hackers
Found in file pp.h
-=item POPl
+=item XPUSHi
-Pops a long off the stack.
+Push an integer onto the stack, extending the stack if necessary. Handles
+'set' magic. See C<PUSHi>.
- long POPl
+ void XPUSHi(IV iv)
=for hackers
Found in file pp.h
-=item POPn
+=item XPUSHn
-Pops a double off the stack.
+Push a double onto the stack, extending the stack if necessary. Handles
+'set' magic. See C<PUSHn>.
- NV POPn
+ void XPUSHn(NV nv)
=for hackers
Found in file pp.h
-=item POPp
+=item XPUSHp
-Pops a string off the stack. Deprecated. New code should provide
-a STRLEN n_a and use POPpx.
+Push a string onto the stack, extending the stack if necessary. The C<len>
+indicates the length of the string. Handles 'set' magic. See
+C<PUSHp>.
- char* POPp
+ void XPUSHp(char* str, STRLEN len)
=for hackers
Found in file pp.h
-=item POPpbytex
+=item XPUSHs
-Pops a string off the stack which must consist of bytes i.e. characters < 256.
-Requires a variable STRLEN n_a in scope.
+Push an SV onto the stack, extending the stack if necessary. Does not
+handle 'set' magic. See C<PUSHs>.
- char* POPpbytex
+ void XPUSHs(SV* sv)
=for hackers
Found in file pp.h
-=item POPpx
+=item XPUSHu
-Pops a string off the stack.
-Requires a variable STRLEN n_a in scope.
+Push an unsigned integer onto the stack, extending the stack if necessary.
+See C<PUSHu>.
- char* POPpx
+ void XPUSHu(UV uv)
=for hackers
Found in file pp.h
-=item POPs
+=item XSRETURN
-Pops an SV off the stack.
+Return from XSUB, indicating number of items on the stack. This is usually
+handled by C<xsubpp>.
- SV* POPs
+ void XSRETURN(int nitems)
=for hackers
-Found in file pp.h
+Found in file XSUB.h
-=item PUSHi
+=item XSRETURN_IV
-Push an integer onto the stack. The stack must have room for this element.
-Handles 'set' magic. See C<XPUSHi>.
+Return an integer from an XSUB immediately. Uses C<XST_mIV>.
- void PUSHi(IV iv)
+ void XSRETURN_IV(IV iv)
=for hackers
-Found in file pp.h
+Found in file XSUB.h
-=item PUSHMARK
+=item XSRETURN_NO
-Opening bracket for arguments on a callback. See C<PUTBACK> and
-L<perlcall>.
+Return C<&PL_sv_no> from an XSUB immediately. Uses C<XST_mNO>.
- PUSHMARK;
+ XSRETURN_NO;
=for hackers
-Found in file pp.h
+Found in file XSUB.h
-=item PUSHn
+=item XSRETURN_NV
-Push a double onto the stack. The stack must have room for this element.
-Handles 'set' magic. See C<XPUSHn>.
+Return a double from an XSUB immediately. Uses C<XST_mNV>.
- void PUSHn(NV nv)
+ void XSRETURN_NV(NV nv)
=for hackers
-Found in file pp.h
+Found in file XSUB.h
-=item PUSHp
+=item XSRETURN_PV
-Push a string onto the stack. The stack must have room for this element.
-The C<len> indicates the length of the string. Handles 'set' magic. See
-C<XPUSHp>.
+Return a copy of a string from an XSUB immediately. Uses C<XST_mPV>.
- void PUSHp(char* str, STRLEN len)
+ void XSRETURN_PV(char* str)
=for hackers
-Found in file pp.h
+Found in file XSUB.h
-=item PUSHs
+=item XSRETURN_UNDEF
-Push an SV onto the stack. The stack must have room for this element.
-Does not handle 'set' magic. See C<XPUSHs>.
+Return C<&PL_sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>.
- void PUSHs(SV* sv)
+ XSRETURN_UNDEF;
=for hackers
-Found in file pp.h
+Found in file XSUB.h
-=item PUSHu
+=item XSRETURN_YES
-Push an unsigned integer onto the stack. The stack must have room for this
-element. See C<XPUSHu>.
+Return C<&PL_sv_yes> from an XSUB immediately. Uses C<XST_mYES>.
- void PUSHu(UV uv)
+ XSRETURN_YES;
=for hackers
-Found in file pp.h
+Found in file XSUB.h
-=item PUTBACK
+=item XST_mIV
-Closing bracket for XSUB arguments. This is usually handled by C<xsubpp>.
-See C<PUSHMARK> and L<perlcall> for other uses.
+Place an integer into the specified position C<pos> on the stack. The
+value is stored in a new mortal SV.
- PUTBACK;
+ void XST_mIV(int pos, IV iv)
=for hackers
-Found in file pp.h
+Found in file XSUB.h
-=item Renew
+=item XST_mNO
-The XSUB-writer's interface to the C C<realloc> function.
+Place C<&PL_sv_no> into the specified position C<pos> on the
+stack.
- void Renew(void* ptr, int nitems, type)
+ void XST_mNO(int pos)
=for hackers
-Found in file handy.h
+Found in file XSUB.h
-=item Renewc
+=item XST_mNV
-The XSUB-writer's interface to the C C<realloc> function, with
-cast.
+Place a double into the specified position C<pos> on the stack. The value
+is stored in a new mortal SV.
- void Renewc(void* ptr, int nitems, type, cast)
+ void XST_mNV(int pos, NV nv)
=for hackers
-Found in file handy.h
-
-=item require_pv
+Found in file XSUB.h
-Tells Perl to C<require> the file named by the string argument. It is
-analogous to the Perl code C<eval "require '$file'">. It's even
-implemented that way; consider using Perl_load_module instead.
+=item XST_mPV
-NOTE: the perl_ form of this function is deprecated.
+Place a copy of a string into the specified position C<pos> on the stack.
+The value is stored in a new mortal SV.
- void require_pv(const char* pv)
+ void XST_mPV(int pos, char* str)
=for hackers
-Found in file perl.c
+Found in file XSUB.h
-=item RETVAL
+=item XST_mUNDEF
-Variable which is setup by C<xsubpp> to hold the return value for an
-XSUB. This is always the proper type for the XSUB. See
-L<perlxs/"The RETVAL Variable">.
+Place C<&PL_sv_undef> into the specified position C<pos> on the
+stack.
- (whatever) RETVAL
+ void XST_mUNDEF(int pos)
=for hackers
Found in file XSUB.h
-=item Safefree
+=item XST_mYES
-The XSUB-writer's interface to the C C<free> function.
+Place C<&PL_sv_yes> into the specified position C<pos> on the
+stack.
- void Safefree(void* ptr)
+ void XST_mYES(int pos)
=for hackers
-Found in file handy.h
+Found in file XSUB.h
-=item savepv
-Copy a string to a safe spot. This does not use an SV.
+=back
- char* savepv(const char* sv)
+=head1 SV Flags
-=for hackers
-Found in file util.c
+=over 8
-=item savepvn
+=item svtype
-Copy a string to a safe spot. The C<len> indicates number of bytes to
-copy. This does not use an SV.
+An enum of flags for Perl types. These are found in the file B<sv.h>
+in the C<svtype> enum. Test these flags with the C<SvTYPE> macro.
+
+=for hackers
+Found in file sv.h
+
+=item SVt_IV
- char* savepvn(const char* sv, I32 len)
+Integer type flag for scalars. See C<svtype>.
=for hackers
-Found in file util.c
+Found in file sv.h
-=item SAVETMPS
+=item SVt_NV
-Opening bracket for temporaries on a callback. See C<FREETMPS> and
-L<perlcall>.
+Double type flag for scalars. See C<svtype>.
- SAVETMPS;
+=for hackers
+Found in file sv.h
+
+=item SVt_PV
+
+Pointer type flag for scalars. See C<svtype>.
=for hackers
-Found in file scope.h
+Found in file sv.h
-=item scan_bin
+=item SVt_PVAV
-For backwards compatibility. Use C<grok_bin> instead.
+Type flag for arrays. See C<svtype>.
- NV scan_bin(char* start, STRLEN len, STRLEN* retlen)
+=for hackers
+Found in file sv.h
+
+=item SVt_PVCV
+
+Type flag for code refs. See C<svtype>.
=for hackers
-Found in file numeric.c
+Found in file sv.h
-=item scan_hex
+=item SVt_PVHV
-For backwards compatibility. Use C<grok_hex> instead.
+Type flag for hashes. See C<svtype>.
- NV scan_hex(char* start, STRLEN len, STRLEN* retlen)
+=for hackers
+Found in file sv.h
+
+=item SVt_PVMG
+
+Type flag for blessed scalars. See C<svtype>.
=for hackers
-Found in file numeric.c
+Found in file sv.h
-=item scan_oct
-For backwards compatibility. Use C<grok_oct> instead.
+=back
- NV scan_oct(char* start, STRLEN len, STRLEN* retlen)
+=head1 SV Manipulation Functions
-=for hackers
-Found in file numeric.c
+=over 8
+
+=item get_sv
-=item sharedsv_find
+Returns the SV of the specified Perl scalar. If C<create> is set and the
+Perl variable does not exist then it will be created. If C<create> is not
+set and the variable does not exist then NULL is returned.
-Tries to find if a given SV has a shared backend, either by
-looking at magic, or by checking if it is tied again threads::shared.
+NOTE: the perl_ form of this function is deprecated.
- shared_sv* sharedsv_find(SV* sv)
+ SV* get_sv(const char* name, I32 create)
=for hackers
-Found in file sharedsv.c
+Found in file perl.c
-=item sharedsv_init
+=item looks_like_number
-Saves a space for keeping SVs wider than an interpreter,
-currently only stores a pointer to the first interpreter.
+Test if the content of an SV looks like a number (or is a number).
+C<Inf> and C<Infinity> are treated as numbers (so will not issue a
+non-numeric warning), even if your atof() doesn't grok them.
- void sharedsv_init()
+ I32 looks_like_number(SV* sv)
=for hackers
-Found in file sharedsv.c
+Found in file sv.c
+
+=item newRV_inc
-=item sharedsv_lock
+Creates an RV wrapper for an SV. The reference count for the original SV is
+incremented.
-Recursive locks on a sharedsv.
-Locks are dynamicly scoped at the level of the first lock.
- void sharedsv_lock(shared_sv* ssv)
+ SV* newRV_inc(SV* sv)
=for hackers
-Found in file sharedsv.c
+Found in file sv.h
+
+=item newRV_noinc
-=item sharedsv_new
+Creates an RV wrapper for an SV. The reference count for the original
+SV is B<not> incremented.
-Allocates a new shared sv struct, you must yourself create the SV/AV/HV.
- shared_sv* sharedsv_new()
+ SV* newRV_noinc(SV *sv)
=for hackers
-Found in file sharedsv.c
+Found in file sv.c
-=item sharedsv_thrcnt_dec
+=item newSV
-Decrements the threadcount of a shared sv. When a threads frontend is freed
-this function should be called.
+Create a new null SV, or if len > 0, create a new empty SVt_PV type SV
+with an initial PV allocation of len+1. Normally accessed via the C<NEWSV>
+macro.
- void sharedsv_thrcnt_dec(shared_sv* ssv)
+ SV* newSV(STRLEN len)
=for hackers
-Found in file sharedsv.c
+Found in file sv.c
+
+=item newSViv
-=item sharedsv_thrcnt_inc
+Creates a new SV and copies an integer into it. The reference count for the
+SV is set to 1.
-Increments the threadcount of a sharedsv.
- void sharedsv_thrcnt_inc(shared_sv* ssv)
+ SV* newSViv(IV i)
=for hackers
-Found in file sharedsv.c
+Found in file sv.c
-=item sharedsv_unlock
+=item newSVnv
-Recursively unlocks a shared sv.
+Creates a new SV and copies a floating point value into it.
+The reference count for the SV is set to 1.
- void sharedsv_unlock(shared_sv* ssv)
+ SV* newSVnv(NV n)
=for hackers
-Found in file sharedsv.c
-
-=item sortsv
+Found in file sv.c
-
-Sort an array. Here is an example:
+=item newSVpv
- sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale);
+Creates a new SV and copies a string into it. The reference count for the
+SV is set to 1. If C<len> is zero, Perl will compute the length using
+strlen(). For efficiency, consider using C<newSVpvn> instead.
- void sortsv(SV ** array, size_t num_elts, SVCOMPARE_t f)
+ SV* newSVpv(const char* s, STRLEN len)
=for hackers
-Found in file pp_ctl.c
+Found in file sv.c
-=item SP
+=item newSVpvf
-Stack pointer. This is usually handled by C<xsubpp>. See C<dSP> and
-C<SPAGAIN>.
+Creates a new SV and initializes it with the string formatted like
+C<sprintf>.
+
+ SV* newSVpvf(const char* pat, ...)
=for hackers
-Found in file pp.h
+Found in file sv.c
-=item SPAGAIN
+=item newSVpvn
-Refetch the stack pointer. Used after a callback. See L<perlcall>.
+Creates a new SV and copies a string into it. The reference count for the
+SV is set to 1. Note that if C<len> is zero, Perl will create a zero length
+string. You are responsible for ensuring that the source string is at least
+C<len> bytes long.
- SPAGAIN;
+ SV* newSVpvn(const char* s, STRLEN len)
=for hackers
-Found in file pp.h
+Found in file sv.c
-=item ST
+=item newSVpvn_share
-Used to access elements on the XSUB's stack.
+Creates a new SV with its SvPVX pointing to a shared string in the string
+table. If the string does not already exist in the table, it is created
+first. Turns on READONLY and FAKE. The string's hash is stored in the UV
+slot of the SV; if the C<hash> parameter is non-zero, that value is used;
+otherwise the hash is computed. The idea here is that as the string table
+is used for shared hash keys these strings will have SvPVX == HeKEY and
+hash lookup will avoid string compare.
- SV* ST(int ix)
+ SV* newSVpvn_share(const char* s, I32 len, U32 hash)
=for hackers
-Found in file XSUB.h
+Found in file sv.c
-=item strEQ
+=item newSVrv
-Test two strings to see if they are equal. Returns true or false.
+Creates a new SV for the RV, C<rv>, to point to. If C<rv> is not an RV then
+it will be upgraded to one. If C<classname> is non-null then the new SV will
+be blessed in the specified package. The new SV is returned and its
+reference count is 1.
- bool strEQ(char* s1, char* s2)
+ SV* newSVrv(SV* rv, const char* classname)
=for hackers
-Found in file handy.h
+Found in file sv.c
-=item strGE
+=item newSVsv
-Test two strings to see if the first, C<s1>, is greater than or equal to
-the second, C<s2>. Returns true or false.
+Creates a new SV which is an exact duplicate of the original SV.
+(Uses C<sv_setsv>).
- bool strGE(char* s1, char* s2)
+ SV* newSVsv(SV* old)
=for hackers
-Found in file handy.h
+Found in file sv.c
-=item strGT
+=item newSVuv
-Test two strings to see if the first, C<s1>, is greater than the second,
-C<s2>. Returns true or false.
+Creates a new SV and copies an unsigned integer into it.
+The reference count for the SV is set to 1.
- bool strGT(char* s1, char* s2)
+ SV* newSVuv(UV u)
=for hackers
-Found in file handy.h
-
-=item strLE
-
-Test two strings to see if the first, C<s1>, is less than or equal to the
-second, C<s2>. Returns true or false.
+Found in file sv.c
- bool strLE(char* s1, char* s2)
+=item new_version
-=for hackers
-Found in file handy.h
+Returns a new version object based on the passed in SV:
-=item strLT
+ SV *sv = new_version(SV *ver);
-Test two strings to see if the first, C<s1>, is less than the second,
-C<s2>. Returns true or false.
+Does not alter the passed in ver SV. See "upg_version" if you
+want to upgrade the SV.
- bool strLT(char* s1, char* s2)
+ SV* new_version(SV *ver)
=for hackers
-Found in file handy.h
-
-=item strNE
+Found in file util.c
-Test two strings to see if they are different. Returns true or
-false.
+=item scan_version
- bool strNE(char* s1, char* s2)
+Returns a pointer to the next character after the parsed
+version string, as well as upgrading the passed in SV to
+an RV.
-=for hackers
-Found in file handy.h
+Function must be called with an already existing SV like
-=item strnEQ
+ sv = NEWSV(92,0);
+ s = scan_version(s,sv);
-Test two strings to see if they are equal. The C<len> parameter indicates
-the number of bytes to compare. Returns true or false. (A wrapper for
-C<strncmp>).
+Performs some preprocessing to the string to ensure that
+it has the correct characteristics of a version. Flags the
+object if it contains an underscore (which denotes this
+is a beta version).
- bool strnEQ(char* s1, char* s2, STRLEN len)
+ char* scan_version(char *vstr, SV *sv)
=for hackers
-Found in file handy.h
-
-=item strnNE
+Found in file util.c
-Test two strings to see if they are different. The C<len> parameter
-indicates the number of bytes to compare. Returns true or false. (A
-wrapper for C<strncmp>).
+=item scan_vstring
- bool strnNE(char* s1, char* s2, STRLEN len)
+Returns a pointer to the next character after the parsed
+vstring, as well as updating the passed in sv.
-=for hackers
-Found in file handy.h
+Function must be called like
-=item StructCopy
+ sv = NEWSV(92,5);
+ s = scan_vstring(s,sv);
-This is an architecture-independent macro to copy one structure to another.
+The sv should already be large enough to store the vstring
+passed in, for performance reasons.
- void StructCopy(type src, type dest, type)
+ char* scan_vstring(char *vstr, SV *sv)
=for hackers
-Found in file handy.h
+Found in file util.c
=item SvCUR
=for hackers
Found in file sv.h
-=item SvGETMAGIC
-
-Invokes C<mg_get> on an SV if it has 'get' magic. This macro evaluates its
-argument more than once.
-
- void SvGETMAGIC(SV* sv)
-
-=for hackers
-Found in file sv.h
-
=item SvGROW
Expands the character buffer in the SV so that it has room for the
=item SvIOK_notUV
-Returns a boolean indicating whether the SV contains an signed integer.
+Returns a boolean indicating whether the SV contains a signed integer.
void SvIOK_notUV(SV* sv)
=item SvPV
-Returns a pointer to the string in the SV, or a stringified form of the SV
-if the SV does not contain a string. Handles 'get' magic. See also
+Returns a pointer to the string in the SV, or a stringified form of
+the SV if the SV does not contain a string. The SV may cache the
+stringified version becoming C<SvPOK>. Handles 'get' magic. See also
C<SvPVx> for a version which guarantees to evaluate sv only once.
char* SvPV(SV* sv, STRLEN len)
=for hackers
Found in file sv.h
-=item SvPVX
+=item SvPVx
-Returns a pointer to the physical string in the SV. The SV must contain a
-string.
+A version of C<SvPV> which guarantees to evaluate sv only once.
- char* SvPVX(SV* sv)
+ char* SvPVx(SV* sv, STRLEN len)
=for hackers
Found in file sv.h
-=item SvPVx
+=item SvPVX
-A version of C<SvPV> which guarantees to evaluate sv only once.
+Returns a pointer to the physical string in the SV. The SV must contain a
+string.
- char* SvPVx(SV* sv, STRLEN len)
+ char* SvPVX(SV* sv)
=for hackers
Found in file sv.h
=item SvPV_force
-Like <SvPV> but will force the SV into becoming a string (SvPOK). You want
-force if you are going to update the SvPVX directly.
+Like C<SvPV> but will force the SV into containing just a string
+(C<SvPOK_only>). You want force if you are going to update the C<SvPVX>
+directly.
char* SvPV_force(SV* sv, STRLEN len)
=item SvPV_force_nomg
-Like <SvPV> but will force the SV into becoming a string (SvPOK). You want
-force if you are going to update the SvPVX directly. Doesn't process magic.
+Like C<SvPV> but will force the SV into containing just a string
+(C<SvPOK_only>). You want force if you are going to update the C<SvPVX>
+directly. Doesn't process magic.
char* SvPV_force_nomg(SV* sv, STRLEN len)
=item SvPV_nolen
-Returns a pointer to the string in the SV, or a stringified form of the SV
-if the SV does not contain a string. Handles 'get' magic.
+Returns a pointer to the string in the SV, or a stringified form of
+the SV if the SV does not contain a string. The SV may cache the
+stringified form becoming C<SvPOK>. Handles 'get' magic.
char* SvPV_nolen(SV* sv)
=for hackers
Found in file sv.h
-=item SvSETMAGIC
-
-Invokes C<mg_set> on an SV if it has 'set' magic. This macro evaluates its
-argument more than once.
-
- void SvSETMAGIC(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvSetMagicSV
-
-Like C<SvSetSV>, but does any set magic required afterwards.
-
- void SvSetMagicSV(SV* dsb, SV* ssv)
-
-=for hackers
-Found in file sv.h
-
-=item SvSetMagicSV_nosteal
-
-Like C<SvSetMagicSV>, but does any set magic required afterwards.
-
- void SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
-
-=for hackers
-Found in file sv.h
-
-=item SvSetSV
-
-Calls C<sv_setsv> if dsv is not the same as ssv. May evaluate arguments
-more than once.
-
- void SvSetSV(SV* dsb, SV* ssv)
-
-=for hackers
-Found in file sv.h
-
-=item SvSetSV_nosteal
-
-Calls a non-destructive version of C<sv_setsv> if dsv is not the same as
-ssv. May evaluate arguments more than once.
-
- void SvSetSV_nosteal(SV* dsv, SV* ssv)
-
-=for hackers
-Found in file sv.h
-
=item SvSTASH
Returns the stash of the SV.
Marks an SV as tainted.
- void SvTAINTED_on(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvTRUE
-
-Returns a boolean indicating whether Perl would evaluate the SV as true or
-false, defined or undefined. Does not handle 'get' magic.
-
- bool SvTRUE(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item svtype
-
-An enum of flags for Perl types. These are found in the file B<sv.h>
-in the C<svtype> enum. Test these flags with the C<SvTYPE> macro.
-
-=for hackers
-Found in file sv.h
-
-=item SvTYPE
-
-Returns the type of the SV. See C<svtype>.
-
- svtype SvTYPE(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SVt_IV
-
-Integer type flag for scalars. See C<svtype>.
-
-=for hackers
-Found in file sv.h
-
-=item SVt_NV
-
-Double type flag for scalars. See C<svtype>.
-
-=for hackers
-Found in file sv.h
-
-=item SVt_PV
-
-Pointer type flag for scalars. See C<svtype>.
+ void SvTAINTED_on(SV* sv)
=for hackers
Found in file sv.h
-=item SVt_PVAV
+=item SvTRUE
-Type flag for arrays. See C<svtype>.
+Returns a boolean indicating whether Perl would evaluate the SV as true or
+false, defined or undefined. Does not handle 'get' magic.
+
+ bool SvTRUE(SV* sv)
=for hackers
Found in file sv.h
-=item SVt_PVCV
+=item SvTYPE
-Type flag for code refs. See C<svtype>.
+Returns the type of the SV. See C<svtype>.
+
+ svtype SvTYPE(SV* sv)
=for hackers
Found in file sv.h
-=item SVt_PVHV
-
-Type flag for hashes. See C<svtype>.
+=item SvUNLOCK
-=for hackers
-Found in file sv.h
+Releases a mutual exclusion lock on sv if a suitable module
+has been loaded.
-=item SVt_PVMG
-Type flag for blessed scalars. See C<svtype>.
+ void SvUNLOCK(SV* sv)
=for hackers
Found in file sv.h
=for hackers
Found in file sv.h
+=item SvUVX
+
+Returns the raw value in the SV's UV slot, without checks or conversions.
+Only use when you are sure SvIOK is true. See also C<SvUV()>.
+
+ UV SvUVX(SV* sv)
+
+=for hackers
+Found in file sv.h
+
=item SvUVx
Coerces the given SV to an unsigned integer and returns it. Guarantees to
=for hackers
Found in file sv.h
-=item SvUVX
+=item SvVOK
-Returns the raw value in the SV's UV slot, without checks or conversions.
-Only use when you are sure SvIOK is true. See also C<SvUV()>.
+Returns a boolean indicating whether the SV contains a v-string.
- UV SvUVX(SV* sv)
+ bool SvVOK(SV* sv)
=for hackers
Found in file sv.h
=for hackers
Found in file sv.c
+=item sv_copypv
+
+Copies a stringified representation of the source SV into the
+destination SV. Automatically performs any necessary mg_get and
+coercion of numeric values into strings. Guaranteed to preserve
+UTF-8 flag even from overloaded objects. Similar in nature to
+sv_2pv[_flags] but operates directly on an SV instead of just the
+string. Mostly uses sv_2pv_flags to do its work, except when that
+would lose the UTF-8'ness of the PV.
+
+ void sv_copypv(SV* dsv, SV* ssv)
+
+=for hackers
+Found in file sv.c
+
=item sv_dec
Auto-decrement of the value in the SV, doing string to numeric conversion
Undo various types of fakery on an SV: if the PV is a shared string, make
a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
-an xpvmg. The C<flags> parameter gets passed to C<sv_unref_flags()>
-when unrefing. C<sv_force_normal> calls this function with flags set to 0.
+an xpvmg; if we're a copy-on-write scalar, this is the on-write time when
+we do the copy, and is also used locally. If C<SV_COW_DROP_PV> is set
+then a copy-on-write scalar drops its PV buffer (if any) and becomes
+SvPOK_off rather than making a copy. (Used where this scalar is about to be
+set to some other value. In addtion, the C<flags> parameter gets passed to
+C<sv_unref_flags()> when unrefing. C<sv_force_normal> calls this function
+with flags set to 0.
void sv_force_normal_flags(SV *sv, U32 flags)
Adds magic to an SV. First upgrades C<sv> to type C<SVt_PVMG> if necessary,
then adds a new magic item of type C<how> to the head of the magic list.
-C<name> is assumed to contain an C<SV*> if C<(name && namelen == HEf_SVKEY)>
-
void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen)
=for hackers
Found in file sv.c
+=item sv_magicext
+
+Adds magic to an SV, upgrading it if necessary. Applies the
+supplied vtable and returns pointer to the magic added.
+
+Note that sv_magicext will allow things that sv_magic will not.
+In particular you can add magic to SvREADONLY SVs and and more than
+one instance of the same 'how'
+
+I C<namelen> is greater then zero then a savepvn() I<copy> of C<name> is stored,
+if C<namelen> is zero then C<name> is stored as-is and - as another special
+case - if C<(name && namelen == HEf_SVKEY)> then C<name> is assumed to contain
+an C<SV*> and has its REFCNT incremented
+
+(This is now used as a subroutine by sv_magic.)
+
+ MAGIC * sv_magicext(SV* sv, SV* obj, int how, MGVTBL *vtbl, const char* name, I32 namlen )
+
+=for hackers
+Found in file sv.c
+
=item sv_mortalcopy
Creates a new SV which is a copy of the original SV (using C<sv_setsv>).
=for hackers
Found in file sv.c
+=item sv_nolocking
+
+Dummy routine which "locks" an SV when there is no locking module present.
+Exists to avoid test for a NULL function pointer and because it could potentially warn under
+some level of strict-ness.
+
+ void sv_nolocking(SV *)
+
+=for hackers
+Found in file util.c
+
+=item sv_nosharing
+
+Dummy routine which "shares" an SV when there is no sharing module present.
+Exists to avoid test for a NULL function pointer and because it could potentially warn under
+some level of strict-ness.
+
+ void sv_nosharing(SV *)
+
+=for hackers
+Found in file util.c
+
+=item sv_nounlocking
+
+Dummy routine which "unlocks" an SV when there is no locking module present.
+Exists to avoid test for a NULL function pointer and because it could potentially warn under
+some level of strict-ness.
+
+ void sv_nounlocking(SV *)
+
+=for hackers
+Found in file util.c
+
=item sv_nv
A private implementation of the C<SvNVx> macro for compilers which can't
=item sv_pv
-A private implementation of the C<SvPV_nolen> macro for compilers which can't
-cope with complex macro expressions. Always use the macro instead.
+Use the C<SvPV_nolen> macro instead
char* sv_pv(SV *sv)
=item sv_pvbyte
-A private implementation of the C<SvPVbyte_nolen> macro for compilers
-which can't cope with complex macro expressions. Always use the macro
-instead.
+Use C<SvPVbyte_nolen> instead.
char* sv_pvbyte(SV *sv)
=item sv_pvutf8
-A private implementation of the C<SvPVutf8_nolen> macro for compilers
-which can't cope with complex macro expressions. Always use the macro
-instead.
+Use the C<SvPVutf8_nolen> macro instead
char* sv_pvutf8(SV *sv)
=for hackers
Found in file sv.c
-=item sv_recode_to_utf8
-
-The encoding is assumed to be an Encode object, on entry the PV
-of the sv is assumed to be octets in that encoding, and the sv
-will be converted into Unicode (and UTF-8).
-
-If the sv already is UTF-8 (or if it is not POK), or if the encoding
-is not a reference, nothing is done to the sv. If the encoding is not
-an C<Encode::XS> Encoding object, bad things will happen.
-(See F<lib/encoding.pm> and L<Encode>).
-
-The PV of the sv is returned.
-
- char* sv_recode_to_utf8(SV* sv, SV *encoding)
-
-=for hackers
-Found in file sv.c
-
=item sv_reftype
Returns a string describing what the SV is a reference to.
=for hackers
Found in file sv.c
-=item sv_setpviv
-
-Copies an integer into the given SV, also updating its string value.
-Does not handle 'set' magic. See C<sv_setpviv_mg>.
-
- void sv_setpviv(SV* sv, IV num)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setpviv_mg
-
-Like C<sv_setpviv>, but also handles 'set' magic.
-
- void sv_setpviv_mg(SV *sv, IV iv)
-
-=for hackers
-Found in file sv.c
-
=item sv_setpvn
Copies a string into an SV. The C<len> parameter indicates the number of
C<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and
C<SvSetMagicSV_nosteal>.
-
void sv_setsv(SV* dsv, SV* ssv)
=for hackers
if this is the case, either returns false or, if C<fail_ok> is not
true, croaks.
+This is not as a general purpose Unicode to byte encoding interface:
+use the Encode extension for that.
+
NOTE: this function is experimental and may change or be
removed without notice.
Always sets the SvUTF8 flag to avoid future validity checks even
if all the bytes have hibit clear.
+This is not as a general purpose byte encoding to Unicode interface:
+use the Encode extension for that.
+
STRLEN sv_utf8_upgrade(SV *sv)
=for hackers
will C<mg_get> on C<sv> if appropriate, else not. C<sv_utf8_upgrade> and
C<sv_utf8_upgrade_nomg> are implemented in terms of this function.
+This is not as a general purpose byte encoding to Unicode interface:
+use the Encode extension for that.
+
STRLEN sv_utf8_upgrade_flags(SV *sv, I32 flags)
=for hackers
void sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
-=for hackers
-Found in file sv.c
+=for hackers
+Found in file sv.c
+
+=item sv_vsetpvfn
+
+Works like C<vcatpvfn> but copies the text into the SV instead of
+appending it.
+
+Usually used via one of its frontends C<sv_setpvf> and C<sv_setpvf_mg>.
+
+ void sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
+
+=for hackers
+Found in file sv.c
+
+=item upg_version
+
+In-place upgrade of the supplied SV to a version object.
+
+ SV *sv = upg_version(SV *sv);
+
+Returns a pointer to the upgraded SV.
+
+ SV* upg_version(SV *ver)
+
+=for hackers
+Found in file util.c
+
+=item vnumify
+
+Accepts a version (or vstring) object and returns the
+normalized floating point representation. Call like:
+
+ sv = vnumify(sv,SvRV(rv));
+
+NOTE: no checking is done to see if the object is of the
+correct type (for speed).
+
+ SV* vnumify(SV *sv, SV *vs)
+
+=for hackers
+Found in file util.c
+
+=item vstringify
+
+Accepts a version (or vstring) object and returns the
+normalized representation. Call like:
+
+ sv = vstringify(sv,SvRV(rv));
+
+NOTE: no checking is done to see if the object is of the
+correct type (for speed).
+
+ SV* vstringify(SV *sv, SV *vs)
+
+=for hackers
+Found in file util.c
+
+
+=back
+
+=head1 Unicode Support
+
+=over 8
+
+=item bytes_from_utf8
+
+Converts a string C<s> of length C<len> from UTF8 into byte encoding.
+Unlike <utf8_to_bytes> but like C<bytes_to_utf8>, returns a pointer to
+the newly-created string, and updates C<len> to contain the new
+length. Returns the original string if no conversion occurs, C<len>
+is unchanged. Do nothing if C<is_utf8> points to 0. Sets C<is_utf8> to
+0 if C<s> is converted or contains all 7bit characters.
+
+NOTE: this function is experimental and may change or be
+removed without notice.
+
+ U8* bytes_from_utf8(U8 *s, STRLEN *len, bool *is_utf8)
+
+=for hackers
+Found in file utf8.c
+
+=item bytes_to_utf8
+
+Converts a string C<s> of length C<len> from ASCII into UTF8 encoding.
+Returns a pointer to the newly-created string, and sets C<len> to
+reflect the new length.
+
+NOTE: this function is experimental and may change or be
+removed without notice.
+
+ U8* bytes_to_utf8(U8 *s, STRLEN *len)
+
+=for hackers
+Found in file utf8.c
+
+=item ibcmp_utf8
+
+Return true if the strings s1 and s2 differ case-insensitively, false
+if not (if they are equal case-insensitively). If u1 is true, the
+string s1 is assumed to be in UTF-8-encoded Unicode. If u2 is true,
+the string s2 is assumed to be in UTF-8-encoded Unicode. If u1 or u2
+are false, the respective string is assumed to be in native 8-bit
+encoding.
+
+If the pe1 and pe2 are non-NULL, the scanning pointers will be copied
+in there (they will point at the beginning of the I<next> character).
+If the pointers behind pe1 or pe2 are non-NULL, they are the end
+pointers beyond which scanning will not continue under any
+circustances. If the byte lengths l1 and l2 are non-zero, s1+l1 and
+s2+l2 will be used as goal end pointers that will also stop the scan,
+and which qualify towards defining a successful match: all the scans
+that define an explicit length must reach their goal pointers for
+a match to succeed).
+
+For case-insensitiveness, the "casefolding" of Unicode is used
+instead of upper/lowercasing both the characters, see
+http://www.unicode.org/unicode/reports/tr21/ (Case Mappings).
+
+ I32 ibcmp_utf8(const char* a, char **pe1, UV l1, bool u1, const char* b, char **pe2, UV l2, bool u2)
+
+=for hackers
+Found in file utf8.c
+
+=item is_utf8_char
+
+Tests if some arbitrary number of bytes begins in a valid UTF-8
+character. Note that an INVARIANT (i.e. ASCII) character is a valid
+UTF-8 character. The actual number of bytes in the UTF-8 character
+will be returned if it is valid, otherwise 0.
+
+ STRLEN is_utf8_char(U8 *p)
+
+=for hackers
+Found in file utf8.c
+
+=item is_utf8_string
+
+Returns true if first C<len> bytes of the given string form a valid UTF8
+string, false otherwise. Note that 'a valid UTF8 string' does not mean
+'a string that contains UTF8' because a valid ASCII string is a valid
+UTF8 string.
+
+ bool is_utf8_string(U8 *s, STRLEN len)
+
+=for hackers
+Found in file utf8.c
+
+=item pv_uni_display
+
+Build to the scalar dsv a displayable version of the string spv,
+length len, the displayable version being at most pvlim bytes long
+(if longer, the rest is truncated and "..." will be appended).
+
+The flags argument can have UNI_DISPLAY_ISPRINT set to display
+isPRINT()able characters as themselves, UNI_DISPLAY_BACKSLASH
+to display the \\[nrfta\\] as the backslashed versions (like '\n')
+(UNI_DISPLAY_BACKSLASH is preferred over UNI_DISPLAY_ISPRINT for \\).
+UNI_DISPLAY_QQ (and its alias UNI_DISPLAY_REGEX) have both
+UNI_DISPLAY_BACKSLASH and UNI_DISPLAY_ISPRINT turned on.
+
+The pointer to the PV of the dsv is returned.
+
+ char* pv_uni_display(SV *dsv, U8 *spv, STRLEN len, STRLEN pvlim, UV flags)
+
+=for hackers
+Found in file utf8.c
+
+=item sv_recode_to_utf8
+
+The encoding is assumed to be an Encode object, on entry the PV
+of the sv is assumed to be octets in that encoding, and the sv
+will be converted into Unicode (and UTF-8).
+
+If the sv already is UTF-8 (or if it is not POK), or if the encoding
+is not a reference, nothing is done to the sv. If the encoding is not
+an C<Encode::XS> Encoding object, bad things will happen.
+(See F<lib/encoding.pm> and L<Encode>).
+
+The PV of the sv is returned.
+
+ char* sv_recode_to_utf8(SV* sv, SV *encoding)
+
+=for hackers
+Found in file sv.c
+
+=item sv_uni_display
+
+Build to the scalar dsv a displayable version of the scalar sv,
+the displayable version being at most pvlim bytes long
+(if longer, the rest is truncated and "..." will be appended).
+
+The flags argument is as in pv_uni_display().
+
+The pointer to the PV of the dsv is returned.
+
+ char* sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags)
+
+=for hackers
+Found in file utf8.c
+
+=item to_utf8_case
+
+The "p" contains the pointer to the UTF-8 string encoding
+the character that is being converted.
+
+The "ustrp" is a pointer to the character buffer to put the
+conversion result to. The "lenp" is a pointer to the length
+of the result.
+
+The "swashp" is a pointer to the swash to use.
-=item sv_vsetpvfn
+Both the special and normal mappings are stored lib/unicore/To/Foo.pl,
+and loaded by SWASHGET, using lib/utf8_heavy.pl. The special (usually,
+but not always, a multicharacter mapping), is tried first.
-Works like C<vcatpvfn> but copies the text into the SV instead of
-appending it.
+The "special" is a string like "utf8::ToSpecLower", which means the
+hash %utf8::ToSpecLower. The access to the hash is through
+Perl_to_utf8_case().
-Usually used via one of its frontends C<sv_setpvf> and C<sv_setpvf_mg>.
+The "normal" is a string like "ToLower" which means the swash
+%utf8::ToLower.
- void sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
+ UV to_utf8_case(U8 *p, U8* ustrp, STRLEN *lenp, SV **swash, char *normal, char *special)
=for hackers
-Found in file sv.c
+Found in file utf8.c
-=item THIS
+=item to_utf8_fold
-Variable which is setup by C<xsubpp> to designate the object in a C++
-XSUB. This is always the proper type for the C++ object. See C<CLASS> and
-L<perlxs/"Using XS With C++">.
+Convert the UTF-8 encoded character at p to its foldcase version and
+store that in UTF-8 in ustrp and its length in bytes in lenp. Note
+that the ustrp needs to be at least UTF8_MAXLEN_FOLD+1 bytes since the
+foldcase version may be longer than the original character (up to
+three characters).
- (whatever) THIS
+The first character of the foldcased version is returned
+(but note, as explained above, that there may be more.)
-=for hackers
-Found in file XSUB.h
+ UV to_utf8_fold(U8 *p, U8* ustrp, STRLEN *lenp)
-=item toLOWER
+=for hackers
+Found in file utf8.c
-Converts the specified character to lowercase.
+=item to_utf8_lower
- char toLOWER(char ch)
+Convert the UTF-8 encoded character at p to its lowercase version and
+store that in UTF-8 in ustrp and its length in bytes in lenp. Note
+that the ustrp needs to be at least UTF8_MAXLEN_UCLC+1 bytes since the
+lowercase version may be longer than the original character (up to two
+characters).
-=for hackers
-Found in file handy.h
+The first character of the lowercased version is returned
+(but note, as explained above, that there may be more.)
-=item toUPPER
+ UV to_utf8_lower(U8 *p, U8* ustrp, STRLEN *lenp)
-Converts the specified character to uppercase.
+=for hackers
+Found in file utf8.c
- char toUPPER(char ch)
+=item to_utf8_title
-=for hackers
-Found in file handy.h
+Convert the UTF-8 encoded character at p to its titlecase version and
+store that in UTF-8 in ustrp and its length in bytes in lenp. Note
+that the ustrp needs to be at least UTF8_MAXLEN_UCLC+1 bytes since the
+titlecase version may be longer than the original character (up to two
+characters).
-=item to_utf8_case
+The first character of the titlecased version is returned
+(but note, as explained above, that there may be more.)
-The "p" contains the pointer to the UTF-8 string encoding
-the character that is being converted.
+ UV to_utf8_title(U8 *p, U8* ustrp, STRLEN *lenp)
-The "ustrp" is a pointer to the character buffer to put the
-conversion result to. The "lenp" is a pointer to the length
-of the result.
+=for hackers
+Found in file utf8.c
-The "swash" is a pointer to the swash to use.
+=item to_utf8_upper
-The "normal" is a string like "ToLower" which means the swash
-$utf8::ToLower, which is stored in lib/unicore/To/Lower.pl,
-and loaded by SWASHGET, using lib/utf8_heavy.pl.
+Convert the UTF-8 encoded character at p to its uppercase version and
+store that in UTF-8 in ustrp and its length in bytes in lenp. Note
+that the ustrp needs to be at least UTF8_MAXLEN_UCLC+1 bytes since the
+uppercase version may be longer than the original character (up to two
+characters).
-The "special" is a string like "utf8::ToSpecLower", which means
-the hash %utf8::ToSpecLower, which is stored in the same file,
-lib/unicore/To/Lower.pl, and also loaded by SWASHGET. The access
-to the hash is by Perl_to_utf8_case().
+The first character of the uppercased version is returned
+(but note, as explained above, that there may be more.)
- UV to_utf8_case(U8 *p, U8* ustrp, STRLEN *lenp, SV **swash, char *normal, char *special)
+ UV to_utf8_upper(U8 *p, U8* ustrp, STRLEN *lenp)
=for hackers
Found in file utf8.c
=for hackers
Found in file utf8.c
-=item uvuni_to_utf8
+=item uvuni_to_utf8_flags
Adds the UTF8 representation of the Unicode codepoint C<uv> to the end
of the string C<d>; C<d> should be have at least C<UTF8_MAXLEN+1> free
bytes available. The return value is the pointer to the byte after the
end of the new character. In other words,
- d = uvuni_to_utf8(d, uv);
-
-is the recommended Unicode-aware way of saying
-
- *(d++) = uv;
-
- U8* uvuni_to_utf8(U8 *d, UV uv)
-
-=for hackers
-Found in file utf8.c
-
-=item warn
-
-This is the XSUB-writer's interface to Perl's C<warn> function. Use this
-function the same way you use the C C<printf> function. See
-C<croak>.
-
- void warn(const char* pat, ...)
-
-=for hackers
-Found in file util.c
-
-=item XPUSHi
-
-Push an integer onto the stack, extending the stack if necessary. Handles
-'set' magic. See C<PUSHi>.
-
- void XPUSHi(IV iv)
-
-=for hackers
-Found in file pp.h
+ d = uvuni_to_utf8_flags(d, uv, flags);
-=item XPUSHn
+or, in most cases,
-Push a double onto the stack, extending the stack if necessary. Handles
-'set' magic. See C<PUSHn>.
+ d = uvuni_to_utf8(d, uv);
- void XPUSHn(NV nv)
+(which is equivalent to)
-=for hackers
-Found in file pp.h
+ d = uvuni_to_utf8_flags(d, uv, 0);
-=item XPUSHp
+is the recommended Unicode-aware way of saying
-Push a string onto the stack, extending the stack if necessary. The C<len>
-indicates the length of the string. Handles 'set' magic. See
-C<PUSHp>.
+ *(d++) = uv;
- void XPUSHp(char* str, STRLEN len)
+ U8* uvuni_to_utf8_flags(U8 *d, UV uv, UV flags)
=for hackers
-Found in file pp.h
-
-=item XPUSHs
-
-Push an SV onto the stack, extending the stack if necessary. Does not
-handle 'set' magic. See C<PUSHs>.
-
- void XPUSHs(SV* sv)
+Found in file utf8.c
-=for hackers
-Found in file pp.h
-=item XPUSHu
+=back
-Push an unsigned integer onto the stack, extending the stack if necessary.
-See C<PUSHu>.
+=head1 Variables created by C<xsubpp> and C<xsubpp> internal functions
- void XPUSHu(UV uv)
+=over 8
-=for hackers
-Found in file pp.h
+=item ax
-=item XS
+Variable which is setup by C<xsubpp> to indicate the stack base offset,
+used by the C<ST>, C<XSprePUSH> and C<XSRETURN> macros. The C<dMARK> macro
+must be called prior to setup the C<MARK> variable.
-Macro to declare an XSUB and its C parameter list. This is handled by
-C<xsubpp>.
+ I32 ax
=for hackers
Found in file XSUB.h
-=item XSRETURN
+=item CLASS
-Return from XSUB, indicating number of items on the stack. This is usually
-handled by C<xsubpp>.
+Variable which is setup by C<xsubpp> to indicate the
+class name for a C++ XS constructor. This is always a C<char*>. See C<THIS>.
- void XSRETURN(int nitems)
+ char* CLASS
=for hackers
Found in file XSUB.h
-=item XSRETURN_EMPTY
+=item dAX
-Return an empty list from an XSUB immediately.
+Sets up the C<ax> variable.
+This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
- XSRETURN_EMPTY;
+ dAX;
=for hackers
Found in file XSUB.h
-=item XSRETURN_IV
+=item dITEMS
-Return an integer from an XSUB immediately. Uses C<XST_mIV>.
+Sets up the C<items> variable.
+This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
- void XSRETURN_IV(IV iv)
+ dITEMS;
=for hackers
Found in file XSUB.h
-=item XSRETURN_NO
+=item dXSARGS
-Return C<&PL_sv_no> from an XSUB immediately. Uses C<XST_mNO>.
+Sets up stack and mark pointers for an XSUB, calling dSP and dMARK.
+Sets up the C<ax> and C<items> variables by calling C<dAX> and C<dITEMS>.
+This is usually handled automatically by C<xsubpp>.
- XSRETURN_NO;
+ dXSARGS;
=for hackers
Found in file XSUB.h
-=item XSRETURN_NV
+=item dXSI32
-Return an double from an XSUB immediately. Uses C<XST_mNV>.
+Sets up the C<ix> variable for an XSUB which has aliases. This is usually
+handled automatically by C<xsubpp>.
- void XSRETURN_NV(NV nv)
+ dXSI32;
=for hackers
Found in file XSUB.h
-=item XSRETURN_PV
+=item items
-Return a copy of a string from an XSUB immediately. Uses C<XST_mPV>.
+Variable which is setup by C<xsubpp> to indicate the number of
+items on the stack. See L<perlxs/"Variable-length Parameter Lists">.
- void XSRETURN_PV(char* str)
+ I32 items
=for hackers
Found in file XSUB.h
-=item XSRETURN_UNDEF
+=item ix
-Return C<&PL_sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>.
+Variable which is setup by C<xsubpp> to indicate which of an
+XSUB's aliases was used to invoke it. See L<perlxs/"The ALIAS: Keyword">.
- XSRETURN_UNDEF;
+ I32 ix
=for hackers
Found in file XSUB.h
-=item XSRETURN_YES
-
-Return C<&PL_sv_yes> from an XSUB immediately. Uses C<XST_mYES>.
+=item newXSproto
- XSRETURN_YES;
+Used by C<xsubpp> to hook up XSUBs as Perl subs. Adds Perl prototypes to
+the subs.
=for hackers
Found in file XSUB.h
-=item XST_mIV
+=item RETVAL
-Place an integer into the specified position C<pos> on the stack. The
-value is stored in a new mortal SV.
+Variable which is setup by C<xsubpp> to hold the return value for an
+XSUB. This is always the proper type for the XSUB. See
+L<perlxs/"The RETVAL Variable">.
- void XST_mIV(int pos, IV iv)
+ (whatever) RETVAL
=for hackers
Found in file XSUB.h
-=item XST_mNO
+=item ST
-Place C<&PL_sv_no> into the specified position C<pos> on the
-stack.
+Used to access elements on the XSUB's stack.
- void XST_mNO(int pos)
+ SV* ST(int ix)
=for hackers
Found in file XSUB.h
-=item XST_mNV
+=item THIS
-Place a double into the specified position C<pos> on the stack. The value
-is stored in a new mortal SV.
+Variable which is setup by C<xsubpp> to designate the object in a C++
+XSUB. This is always the proper type for the C++ object. See C<CLASS> and
+L<perlxs/"Using XS With C++">.
- void XST_mNV(int pos, NV nv)
+ (whatever) THIS
=for hackers
Found in file XSUB.h
-=item XST_mPV
-
-Place a copy of a string into the specified position C<pos> on the stack.
-The value is stored in a new mortal SV.
+=item XS
- void XST_mPV(int pos, char* str)
+Macro to declare an XSUB and its C parameter list. This is handled by
+C<xsubpp>.
=for hackers
Found in file XSUB.h
-=item XST_mUNDEF
-
-Place C<&PL_sv_undef> into the specified position C<pos> on the
-stack.
-
- void XST_mUNDEF(int pos)
-
-=for hackers
-Found in file XSUB.h
+=item XSRETURN_EMPTY
-=item XST_mYES
+Return an empty list from an XSUB immediately.
-Place C<&PL_sv_yes> into the specified position C<pos> on the
-stack.
- void XST_mYES(int pos)
+ XSRETURN_EMPTY;
=for hackers
Found in file XSUB.h
=for hackers
Found in file XSUB.h
-=item Zero
-The XSUB-writer's interface to the C C<memzero> function. The C<dest> is the
-destination, C<nitems> is the number of items, and C<type> is the type.
+=back
- void Zero(void* dest, int nitems, type)
+=head1 Warning and Dieing
+
+=over 8
+
+=item croak
+
+This is the XSUB-writer's interface to Perl's C<die> function.
+Normally use this function the same way you use the C C<printf>
+function. See C<warn>.
+
+If you want to throw an exception object, assign the object to
+C<$@> and then pass C<Nullch> to croak():
+
+ errsv = get_sv("@", TRUE);
+ sv_setsv(errsv, exception_object);
+ croak(Nullch);
+
+ void croak(const char* pat, ...)
=for hackers
-Found in file handy.h
+Found in file util.c
+
+=item warn
+
+This is the XSUB-writer's interface to Perl's C<warn> function. Use this
+function the same way you use the C C<printf> function. See
+C<croak>.
+
+ void warn(const char* pat, ...)
+
+=for hackers
+Found in file util.c
+
=back