+++ /dev/null
--*- buffer-read-only: t -*-
-
-!!!!!!! DO NOT EDIT THIS FILE !!!!!!!
-This file is built by autodoc.pl extracting documentation from the C source
-files.
-
-=head1 NAME
-
-perlapi - autogenerated documentation for the perl public API
-
-=head1 DESCRIPTION
-X<Perl API> X<API> X<api>
-
-This file contains the documentation of the perl public API generated by
-embed.pl, specifically a listing of functions, macros, flags, and variables
-that may be used by extension writers. The interfaces of any functions that
-are not listed here are subject to change without notice. For this reason,
-blindly using functions listed in proto.h is to be avoided when writing
-extensions.
-
-Note that all Perl API global variables must be referenced with the C<PL_>
-prefix. Some macros are provided for compatibility with the older,
-unadorned names, but this support may be disabled in a future release.
-
-Perl was originally written to handle US-ASCII only (that is characters
-whose ordinal numbers are in the range 0 - 127).
-And documentation and comments may still use the term ASCII, when
-sometimes in fact the entire range from 0 - 255 is meant.
-
-Note that Perl can be compiled and run under EBCDIC (See L<perlebcdic>)
-or ASCII. Most of the documentation (and even comments in the code)
-ignore the EBCDIC possibility.
-For almost all purposes the differences are transparent.
-As an example, under EBCDIC,
-instead of UTF-8, UTF-EBCDIC is used to encode Unicode strings, and so
-whenever this documentation refers to C<utf8>
-(and variants of that name, including in function names),
-it also (essentially transparently) means C<UTF-EBCDIC>.
-But the ordinals of characters differ between ASCII, EBCDIC, and
-the UTF- encodings, and a string encoded in UTF-EBCDIC may occupy more bytes
-than in UTF-8.
-
-Also, on some EBCDIC machines, functions that are documented as operating on
-US-ASCII (or Basic Latin in Unicode terminology) may in fact operate on all
-256 characters in the EBCDIC range, not just the subset corresponding to
-US-ASCII.
-
-The listing below is alphabetical, case insensitive.
-
-
-=head1 "Gimme" Values
-
-=over 8
-
-=item GIMME
-X<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
-X<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
-X<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
-X<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
-X<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
-X<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
-X<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
-X<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
-X<AvFILL>
-
-Same as C<av_len()>. Deprecated, use C<av_len()> instead.
-
- int AvFILL(AV* av)
-
-=for hackers
-Found in file av.h
-
-=item av_clear
-X<av_clear>
-
-Clears an array, making it empty. Does not free the memory used by the
-array itself.
-
- void av_clear(AV *av)
-
-=for hackers
-Found in file av.c
-
-=item av_create_and_push
-X<av_create_and_push>
-
-Push an SV onto the end of the array, creating the array if necessary.
-A small internal helper function to remove a commonly duplicated idiom.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- void av_create_and_push(AV **const avp, SV *const val)
-
-=for hackers
-Found in file av.c
-
-=item av_create_and_unshift_one
-X<av_create_and_unshift_one>
-
-Unshifts an SV onto the beginning of the array, creating the array if
-necessary.
-A small internal helper function to remove a commonly duplicated idiom.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- SV** av_create_and_unshift_one(AV **const avp, SV *const val)
-
-=for hackers
-Found in file av.c
-
-=item av_delete
-X<av_delete>
-
-Deletes the element indexed by C<key> from the array. Returns the
-deleted element. If C<flags> equals C<G_DISCARD>, the element is freed
-and null is returned.
-
- SV* av_delete(AV *av, I32 key, I32 flags)
-
-=for hackers
-Found in file av.c
-
-=item av_exists
-X<av_exists>
-
-Returns true if the element indexed by C<key> has been initialized.
-
-This relies on the fact that uninitialized array elements are set to
-C<&PL_sv_undef>.
-
- bool av_exists(AV *av, I32 key)
-
-=for hackers
-Found in file av.c
-
-=item av_extend
-X<av_extend>
-
-Pre-extend an array. The C<key> is the index to which the array should be
-extended.
-
- void av_extend(AV *av, I32 key)
-
-=for hackers
-Found in file av.c
-
-=item av_fetch
-X<av_fetch>
-
-Returns the SV at the specified index in the array. The C<key> is the
-index. 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*>.
-
-See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
-more information on how to use this function on tied arrays.
-
- SV** av_fetch(AV *av, I32 key, I32 lval)
-
-=for hackers
-Found in file av.c
-
-=item av_fill
-X<av_fill>
-
-Set the highest index in the array to the given number, equivalent to
-Perl's C<$#array = $fill;>.
-
-The number of elements in the an array will be C<fill + 1> after
-av_fill() returns. If the array was previously shorter then the
-additional elements appended are set to C<PL_sv_undef>. If the array
-was longer, then the excess elements are freed. C<av_fill(av, -1)> is
-the same as C<av_clear(av)>.
-
- void av_fill(AV *av, I32 fill)
-
-=for hackers
-Found in file av.c
-
-=item av_len
-X<av_len>
-
-Returns the highest index in the array. The number of elements in the
-array is C<av_len(av) + 1>. Returns -1 if the array is empty.
-
- I32 av_len(AV *av)
-
-=for hackers
-Found in file av.c
-
-=item av_make
-X<av_make>
-
-Creates a new AV and populates it with a list of SVs. The SVs are copied
-into the array, so they may be freed after the call to av_make. The new AV
-will have a reference count of 1.
-
- AV* av_make(I32 size, SV **strp)
-
-=for hackers
-Found in file av.c
-
-=item av_pop
-X<av_pop>
-
-Pops an SV off the end of the array. Returns C<&PL_sv_undef> if the array
-is empty.
-
- SV* av_pop(AV *av)
-
-=for hackers
-Found in file av.c
-
-=item av_push
-X<av_push>
-
-Pushes an SV onto the end of the array. The array will grow automatically
-to accommodate the addition.
-
- void av_push(AV *av, SV *val)
-
-=for hackers
-Found in file av.c
-
-=item av_shift
-X<av_shift>
-
-Shifts an SV off the beginning of the array. Returns C<&PL_sv_undef> if the
-array is empty.
-
- SV* av_shift(AV *av)
-
-=for hackers
-Found in file av.c
-
-=item av_store
-X<av_store>
-
-Stores an SV in an array. The array index is specified as C<key>. The
-return value will be NULL if the operation failed or if the value did not
-need to be actually stored within the array (as in the case of tied
-arrays). 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 arrays.
-
- SV** av_store(AV *av, I32 key, SV *val)
-
-=for hackers
-Found in file av.c
-
-=item av_undef
-X<av_undef>
-
-Undefines the array. Frees the memory used by the array itself.
-
- void av_undef(AV *av)
-
-=for hackers
-Found in file av.c
-
-=item av_unshift
-X<av_unshift>
-
-Unshift the given number of C<undef> values onto the beginning of the
-array. The array will grow automatically to accommodate the addition. You
-must then use C<av_store> to assign values to these new elements.
-
- void av_unshift(AV *av, I32 num)
-
-=for hackers
-Found in file av.c
-
-=item get_av
-X<get_av>
-
-Returns the AV of the specified Perl array. C<flags> are passed to
-C<gv_fetchpv>. If C<GV_ADD> is set and the
-Perl variable does not exist then it will be created. If C<flags> is zero
-and the variable does not exist then NULL is returned.
-
-NOTE: the perl_ form of this function is deprecated.
-
- AV* get_av(const char *name, I32 flags)
-
-=for hackers
-Found in file perl.c
-
-=item newAV
-X<newAV>
-
-Creates a new AV. The reference count is set to 1.
-
- AV* newAV()
-
-=for hackers
-Found in file av.h
-
-=item sortsv
-X<sortsv>
-
-Sort an array. Here is an example:
-
- sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale);
-
-Currently this always uses mergesort. See sortsv_flags for a more
-flexible routine.
-
- void sortsv(SV** array, size_t num_elts, SVCOMPARE_t cmp)
-
-=for hackers
-Found in file pp_sort.c
-
-=item sortsv_flags
-X<sortsv_flags>
-
-Sort an array, with various options.
-
- void sortsv_flags(SV** array, size_t num_elts, SVCOMPARE_t cmp, U32 flags)
-
-=for hackers
-Found in file pp_sort.c
-
-
-=back
-
-=head1 Callback Functions
-
-=over 8
-
-=item call_argv
-X<call_argv>
-
-Performs a callback to the specified Perl sub. See L<perlcall>.
-
-NOTE: the perl_ form of this function is deprecated.
-
- I32 call_argv(const char* sub_name, I32 flags, char** argv)
-
-=for hackers
-Found in file perl.c
-
-=item call_method
-X<call_method>
-
-Performs a callback to the specified Perl method. The blessed object must
-be on the stack. See L<perlcall>.
-
-NOTE: the perl_ form of this function is deprecated.
-
- I32 call_method(const char* methname, I32 flags)
-
-=for hackers
-Found in file perl.c
-
-=item call_pv
-X<call_pv>
-
-Performs a callback to the specified Perl sub. See L<perlcall>.
-
-NOTE: the perl_ form of this function is deprecated.
-
- I32 call_pv(const char* sub_name, I32 flags)
-
-=for hackers
-Found in file perl.c
-
-=item call_sv
-X<call_sv>
-
-Performs a callback to the Perl sub whose name is in the SV. See
-L<perlcall>.
-
-NOTE: the perl_ form of this function is deprecated.
-
- I32 call_sv(SV* sv, VOL I32 flags)
-
-=for hackers
-Found in file perl.c
-
-=item ENTER
-X<ENTER>
-
-Opening bracket on a callback. See C<LEAVE> and L<perlcall>.
-
- ENTER;
-
-=for hackers
-Found in file scope.h
-
-=item eval_pv
-X<eval_pv>
-
-Tells Perl to C<eval> the given string and return an SV* result.
-
-NOTE: the perl_ form of this function is deprecated.
-
- SV* eval_pv(const char* p, I32 croak_on_error)
-
-=for hackers
-Found in file perl.c
-
-=item eval_sv
-X<eval_sv>
-
-Tells Perl to C<eval> the string in the SV.
-
-NOTE: the perl_ form of this function is deprecated.
-
- I32 eval_sv(SV* sv, I32 flags)
-
-=for hackers
-Found in file perl.c
-
-=item FREETMPS
-X<FREETMPS>
-
-Closing bracket for temporaries on a callback. See C<SAVETMPS> and
-L<perlcall>.
-
- FREETMPS;
-
-=for hackers
-Found in file scope.h
-
-=item LEAVE
-X<LEAVE>
-
-Closing bracket on a callback. See C<ENTER> and L<perlcall>.
-
- LEAVE;
-
-=for hackers
-Found in file scope.h
-
-=item SAVETMPS
-X<SAVETMPS>
-
-Opening bracket for temporaries on a callback. See C<FREETMPS> and
-L<perlcall>.
-
- SAVETMPS;
-
-=for hackers
-Found in file scope.h
-
-
-=back
-
-=head1 Character classes
-
-=over 8
-
-=item isALNUM
-X<isALNUM>
-
-Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin)
-alphanumeric character (including underscore) or digit.
-
- bool isALNUM(char ch)
-
-=for hackers
-Found in file handy.h
-
-=item isALPHA
-X<isALPHA>
-
-Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin)
-alphabetic character.
-
- bool isALPHA(char ch)
-
-=for hackers
-Found in file handy.h
-
-=item isDIGIT
-X<isDIGIT>
-
-Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin)
-digit.
-
- bool isDIGIT(char ch)
-
-=for hackers
-Found in file handy.h
-
-=item isLOWER
-X<isLOWER>
-
-Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin)
-lowercase character.
-
- bool isLOWER(char ch)
-
-=for hackers
-Found in file handy.h
-
-=item isSPACE
-X<isSPACE>
-
-Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin)
-whitespace.
-
- bool isSPACE(char ch)
-
-=for hackers
-Found in file handy.h
-
-=item isUPPER
-X<isUPPER>
-
-Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin)
-uppercase character.
-
- bool isUPPER(char ch)
-
-=for hackers
-Found in file handy.h
-
-=item toLOWER
-X<toLOWER>
-
-Converts the specified character to lowercase. Characters outside the
-US-ASCII (Basic Latin) range are viewed as not having any case.
-
- char toLOWER(char ch)
-
-=for hackers
-Found in file handy.h
-
-=item toUPPER
-X<toUPPER>
-
-Converts the specified character to uppercase. Characters outside the
-US-ASCII (Basic Latin) range are viewed as not having any case.
-
- char toUPPER(char ch)
-
-=for hackers
-Found in file handy.h
-
-
-=back
-
-=head1 Cloning an interpreter
-
-=over 8
-
-=item perl_clone
-X<perl_clone>
-
-Create and return a new interpreter by cloning the current one.
-
-perl_clone takes these flags as parameters:
-
-CLONEf_COPY_STACKS - is used to, well, copy the stacks also,
-without it we only clone the data and zero the stacks,
-with it we copy the stacks and the new perl interpreter is
-ready to run at the exact same point as the previous one.
-The pseudo-fork code uses COPY_STACKS while the
-threads->create doesn't.
-
-CLONEf_KEEP_PTR_TABLE
-perl_clone keeps a ptr_table with the pointer of the old
-variable as a key and the new variable as a value,
-this allows it to check if something has been cloned and not
-clone it again but rather just use the value and increase the
-refcount. If KEEP_PTR_TABLE is not set then perl_clone will kill
-the ptr_table using the function
-C<ptr_table_free(PL_ptr_table); PL_ptr_table = NULL;>,
-reason to keep it around is if you want to dup some of your own
-variable who are outside the graph perl scans, example of this
-code is in threads.xs create
-
-CLONEf_CLONE_HOST
-This is a win32 thing, it is ignored on unix, it tells perls
-win32host code (which is c++) to clone itself, this is needed on
-win32 if you want to run two threads at the same time,
-if you just want to do some stuff in a separate perl interpreter
-and then throw it away and return to the original one,
-you don't need to do anything.
-
- PerlInterpreter* perl_clone(PerlInterpreter *proto_perl, UV flags)
-
-=for hackers
-Found in file sv.c
-
-
-=back
-
-=head1 CV Manipulation Functions
-
-=over 8
-
-=item CvSTASH
-X<CvSTASH>
-
-Returns the stash of the CV.
-
- HV* CvSTASH(CV* cv)
-
-=for hackers
-Found in file cv.h
-
-=item get_cv
-X<get_cv>
-
-Uses C<strlen> to get the length of C<name>, then calls C<get_cvn_flags>.
-
-NOTE: the perl_ form of this function is deprecated.
-
- CV* get_cv(const char* name, I32 flags)
-
-=for hackers
-Found in file perl.c
-
-=item get_cvn_flags
-X<get_cvn_flags>
-
-Returns the CV of the specified Perl subroutine. C<flags> are passed to
-C<gv_fetchpvn_flags>. If C<GV_ADD> 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<GV_ADD> is not set and the subroutine does not exist
-then NULL is returned.
-
-NOTE: the perl_ form of this function is deprecated.
-
- CV* get_cvn_flags(const char* name, STRLEN len, I32 flags)
-
-=for hackers
-Found in file perl.c
-
-
-=back
-
-=head1 Embedding Functions
-
-=over 8
-
-=item cv_undef
-X<cv_undef>
-
-Clear out all the active components of a CV. This can happen either
-by an explicit C<undef &foo>, or by the reference count going to zero.
-In the former case, we keep the CvOUTSIDE pointer, so that any anonymous
-children can still follow the full lexical scope chain.
-
- void cv_undef(CV* cv)
-
-=for hackers
-Found in file op.c
-
-=item load_module
-X<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 op.c
-
-=item nothreadhook
-X<nothreadhook>
-
-Stub that provides thread hook for perl_destruct when there are
-no threads.
-
- int nothreadhook()
-
-=for hackers
-Found in file perl.c
-
-=item perl_alloc
-X<perl_alloc>
-
-Allocates a new Perl interpreter. See L<perlembed>.
-
- PerlInterpreter* perl_alloc()
-
-=for hackers
-Found in file perl.c
-
-=item perl_construct
-X<perl_construct>
-
-Initializes a new Perl interpreter. See L<perlembed>.
-
- void perl_construct(PerlInterpreter *my_perl)
-
-=for hackers
-Found in file perl.c
-
-=item perl_destruct
-X<perl_destruct>
-
-Shuts down a Perl interpreter. See L<perlembed>.
-
- int perl_destruct(PerlInterpreter *my_perl)
-
-=for hackers
-Found in file perl.c
-
-=item perl_free
-X<perl_free>
-
-Releases a Perl interpreter. See L<perlembed>.
-
- void perl_free(PerlInterpreter *my_perl)
-
-=for hackers
-Found in file perl.c
-
-=item perl_parse
-X<perl_parse>
-
-Tells a Perl interpreter to parse a Perl script. See L<perlembed>.
-
- int perl_parse(PerlInterpreter *my_perl, XSINIT_t xsinit, int argc, char** argv, char** env)
-
-=for hackers
-Found in file perl.c
-
-=item perl_run
-X<perl_run>
-
-Tells a Perl interpreter to run. See L<perlembed>.
-
- int perl_run(PerlInterpreter *my_perl)
-
-=for hackers
-Found in file perl.c
-
-=item require_pv
-X<require_pv>
-
-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 load_module instead.
-
-NOTE: the perl_ form of this function is deprecated.
-
- void require_pv(const char* pv)
-
-=for hackers
-Found in file perl.c
-
-
-=back
-
-=head1 Functions in file dump.c
-
-
-=over 8
-
-=item pv_display
-X<pv_display>
-
-Similar to
-
- pv_escape(dsv,pv,cur,pvlim,PERL_PV_ESCAPE_QUOTE);
-
-except that an additional "\0" will be appended to the string when
-len > cur and pv[cur] is "\0".
-
-Note that the final string may be up to 7 chars longer than pvlim.
-
- char* pv_display(SV *dsv, const char *pv, STRLEN cur, STRLEN len, STRLEN pvlim)
-
-=for hackers
-Found in file dump.c
-
-=item pv_escape
-X<pv_escape>
-
-Escapes at most the first "count" chars of pv and puts the results into
-dsv such that the size of the escaped string will not exceed "max" chars
-and will not contain any incomplete escape sequences.
-
-If flags contains PERL_PV_ESCAPE_QUOTE then any double quotes in the string
-will also be escaped.
-
-Normally the SV will be cleared before the escaped string is prepared,
-but when PERL_PV_ESCAPE_NOCLEAR is set this will not occur.
-
-If PERL_PV_ESCAPE_UNI is set then the input string is treated as Unicode,
-if PERL_PV_ESCAPE_UNI_DETECT is set then the input string is scanned
-using C<is_utf8_string()> to determine if it is Unicode.
-
-If PERL_PV_ESCAPE_ALL is set then all input chars will be output
-using C<\x01F1> style escapes, otherwise only chars above 255 will be
-escaped using this style, other non printable chars will use octal or
-common escaped patterns like C<\n>. If PERL_PV_ESCAPE_NOBACKSLASH
-then all chars below 255 will be treated as printable and
-will be output as literals.
-
-If PERL_PV_ESCAPE_FIRSTCHAR is set then only the first char of the
-string will be escaped, regardles of max. If the string is utf8 and
-the chars value is >255 then it will be returned as a plain hex
-sequence. Thus the output will either be a single char,
-an octal escape sequence, a special escape like C<\n> or a 3 or
-more digit hex value.
-
-If PERL_PV_ESCAPE_RE is set then the escape char used will be a '%' and
-not a '\\'. This is because regexes very often contain backslashed
-sequences, whereas '%' is not a particularly common character in patterns.
-
-Returns a pointer to the escaped text as held by dsv.
-
- char* pv_escape(SV *dsv, char const * const str, const STRLEN count, const STRLEN max, STRLEN * const escaped, const U32 flags)
-
-=for hackers
-Found in file dump.c
-
-=item pv_pretty
-X<pv_pretty>
-
-Converts a string into something presentable, handling escaping via
-pv_escape() and supporting quoting and ellipses.
-
-If the PERL_PV_PRETTY_QUOTE flag is set then the result will be
-double quoted with any double quotes in the string escaped. Otherwise
-if the PERL_PV_PRETTY_LTGT flag is set then the result be wrapped in
-angle brackets.
-
-If the PERL_PV_PRETTY_ELLIPSES flag is set and not all characters in
-string were output then an ellipsis C<...> will be appended to the
-string. Note that this happens AFTER it has been quoted.
-
-If start_color is non-null then it will be inserted after the opening
-quote (if there is one) but before the escaped text. If end_color
-is non-null then it will be inserted after the escaped text but before
-any quotes or ellipses.
-
-Returns a pointer to the prettified text as held by dsv.
-
- char* pv_pretty(SV *dsv, char const * const str, const STRLEN count, const STRLEN max, char const * const start_color, char const * const end_color, const U32 flags)
-
-=for hackers
-Found in file dump.c
-
-
-=back
-
-=head1 Functions in file mathoms.c
-
-
-=over 8
-
-=item gv_fetchmethod
-X<gv_fetchmethod>
-
-See L<gv_fetchmethod_autoload>.
-
- GV* gv_fetchmethod(HV* stash, const char* name)
-
-=for hackers
-Found in file mathoms.c
-
-=item pack_cat
-X<pack_cat>
-
-The engine implementing pack() Perl function. Note: parameters next_in_list and
-flags are not used. This call should not be used; use packlist instead.
-
- void pack_cat(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_2pvbyte_nolen
-X<sv_2pvbyte_nolen>
-
-Return a pointer to the byte-encoded representation of the SV.
-May cause the SV to be downgraded from UTF-8 as a side-effect.
-
-Usually accessed via the C<SvPVbyte_nolen> macro.
-
- char* sv_2pvbyte_nolen(SV* sv)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_2pvutf8_nolen
-X<sv_2pvutf8_nolen>
-
-Return a pointer to the UTF-8-encoded representation of the SV.
-May cause the SV to be upgraded to UTF-8 as a side-effect.
-
-Usually accessed via the C<SvPVutf8_nolen> macro.
-
- char* sv_2pvutf8_nolen(SV* sv)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_2pv_nolen
-X<sv_2pv_nolen>
-
-Like C<sv_2pv()>, but doesn't return the length too. You should usually
-use the macro wrapper C<SvPV_nolen(sv)> instead.
- char* sv_2pv_nolen(SV* sv)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_catpvn_mg
-X<sv_catpvn_mg>
-
-Like C<sv_catpvn>, but also handles 'set' magic.
-
- void sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_catsv_mg
-X<sv_catsv_mg>
-
-Like C<sv_catsv>, but also handles 'set' magic.
-
- void sv_catsv_mg(SV *dsv, SV *ssv)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_force_normal
-X<sv_force_normal>
-
-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. See also C<sv_force_normal_flags>.
-
- void sv_force_normal(SV *sv)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_iv
-X<sv_iv>
-
-A private implementation of the C<SvIVx> macro for compilers which can't
-cope with complex macro expressions. Always use the macro instead.
-
- IV sv_iv(SV* sv)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_nolocking
-X<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.
-
-"Superseded" by sv_nosharing().
-
- void sv_nolocking(SV *sv)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_nounlocking
-X<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.
-
-"Superseded" by sv_nosharing().
-
- void sv_nounlocking(SV *sv)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_nv
-X<sv_nv>
-
-A private implementation of the C<SvNVx> macro for compilers which can't
-cope with complex macro expressions. Always use the macro instead.
-
- NV sv_nv(SV* sv)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_pv
-X<sv_pv>
-
-Use the C<SvPV_nolen> macro instead
-
- char* sv_pv(SV *sv)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_pvbyte
-X<sv_pvbyte>
-
-Use C<SvPVbyte_nolen> instead.
-
- char* sv_pvbyte(SV *sv)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_pvbyten
-X<sv_pvbyten>
-
-A private implementation of the C<SvPVbyte> macro for compilers
-which can't cope with complex macro expressions. Always use the macro
-instead.
-
- char* sv_pvbyten(SV *sv, STRLEN *lp)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_pvn
-X<sv_pvn>
-
-A private implementation of the C<SvPV> macro for compilers which can't
-cope with complex macro expressions. Always use the macro instead.
-
- char* sv_pvn(SV *sv, STRLEN *lp)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_pvutf8
-X<sv_pvutf8>
-
-Use the C<SvPVutf8_nolen> macro instead
-
- char* sv_pvutf8(SV *sv)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_pvutf8n
-X<sv_pvutf8n>
-
-A private implementation of the C<SvPVutf8> macro for compilers
-which can't cope with complex macro expressions. Always use the macro
-instead.
-
- char* sv_pvutf8n(SV *sv, STRLEN *lp)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_taint
-X<sv_taint>
-
-Taint an SV. Use C<SvTAINTED_on> instead.
- void sv_taint(SV* sv)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_unref
-X<sv_unref>
-
-Unsets the RV status of the SV, and decrements the reference count of
-whatever was being referenced by the RV. This can almost be thought of
-as a reversal of C<newSVrv>. This is C<sv_unref_flags> with the C<flag>
-being zero. See C<SvROK_off>.
-
- void sv_unref(SV* sv)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_usepvn
-X<sv_usepvn>
-
-Tells an SV to use C<ptr> to find its string value. Implemented by
-calling C<sv_usepvn_flags> with C<flags> of 0, hence does not handle 'set'
-magic. See C<sv_usepvn_flags>.
-
- void sv_usepvn(SV* sv, char* ptr, STRLEN len)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_usepvn_mg
-X<sv_usepvn_mg>
-
-Like C<sv_usepvn>, but also handles 'set' magic.
-
- void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
-
-=for hackers
-Found in file mathoms.c
-
-=item sv_uv
-X<sv_uv>
-
-A private implementation of the C<SvUVx> macro for compilers which can't
-cope with complex macro expressions. Always use the macro instead.
-
- UV sv_uv(SV* sv)
-
-=for hackers
-Found in file mathoms.c
-
-=item unpack_str
-X<unpack_str>
-
-The engine implementing unpack() Perl function. Note: parameters strbeg, new_s
-and ocnt are not used. This call should not be used, use unpackstring instead.
-
- I32 unpack_str(const char *pat, const char *patend, const char *s, const char *strbeg, const char *strend, char **new_s, I32 ocnt, U32 flags)
-
-=for hackers
-Found in file mathoms.c
-
-
-=back
-
-=head1 Functions in file perl.h
-
-
-=over 8
-
-=item PERL_SYS_INIT
-X<PERL_SYS_INIT>
-
-Provides system-specific tune up of the C runtime environment necessary to
-run Perl interpreters. This should be called only once, before creating
-any Perl interpreters.
-
- void PERL_SYS_INIT(int argc, char** argv)
-
-=for hackers
-Found in file perl.h
-
-=item PERL_SYS_INIT3
-X<PERL_SYS_INIT3>
-
-Provides system-specific tune up of the C runtime environment necessary to
-run Perl interpreters. This should be called only once, before creating
-any Perl interpreters.
-
- void PERL_SYS_INIT3(int argc, char** argv, char** env)
-
-=for hackers
-Found in file perl.h
-
-=item PERL_SYS_TERM
-X<PERL_SYS_TERM>
-
-Provides system-specific clean up of the C runtime environment after
-running Perl interpreters. This should be called only once, after
-freeing any remaining Perl interpreters.
-
- void PERL_SYS_TERM()
-
-=for hackers
-Found in file perl.h
-
-
-=back
-
-=head1 Functions in file pp_ctl.c
-
-
-=over 8
-
-=item find_runcv
-X<find_runcv>
-
-Locate the CV corresponding to the currently executing sub or eval.
-If db_seqp is non_null, skip CVs that are in the DB package and populate
-*db_seqp with the cop sequence number at the point that the DB:: code was
-entered. (allows debuggers to eval in the scope of the breakpoint rather
-than in the scope of the debugger itself).
-
- CV* find_runcv(U32 *db_seqp)
-
-=for hackers
-Found in file pp_ctl.c
-
-
-=back
-
-=head1 Functions in file pp_pack.c
-
-
-=over 8
-
-=item packlist
-X<packlist>
-
-The engine implementing pack() Perl function.
-
- void packlist(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist)
-
-=for hackers
-Found in file pp_pack.c
-
-=item unpackstring
-X<unpackstring>
-
-The engine implementing unpack() Perl function. C<unpackstring> puts the
-extracted list items on the stack and returns the number of elements.
-Issue C<PUTBACK> before and C<SPAGAIN> after the call to this function.
-
- I32 unpackstring(const char *pat, const char *patend, const char *s, const char *strend, U32 flags)
-
-=for hackers
-Found in file pp_pack.c
-
-
-=back
-
-=head1 Functions in file pp_sys.c
-
-
-=over 8
-
-=item setdefout
-X<setdefout>
-
-Sets PL_defoutgv, the default file handle for output, to the passed in
-typeglob. As PL_defoutgv "owns" a reference on its typeglob, the reference
-count of the passed in typeglob is increased by one, and the reference count
-of the typeglob that PL_defoutgv points to is decreased by one.
-
- void setdefout(GV* gv)
-
-=for hackers
-Found in file pp_sys.c
-
-
-=back
-
-=head1 GV Functions
-
-=over 8
-
-=item GvSV
-X<GvSV>
-
-Return the SV from the GV.
-
- SV* GvSV(GV* gv)
-
-=for hackers
-Found in file gv.h
-
-=item gv_const_sv
-X<gv_const_sv>
-
-If C<gv> is a typeglob whose subroutine entry is a constant sub eligible for
-inlining, or C<gv> is a placeholder reference that would be promoted to such
-a typeglob, then returns the value returned by the sub. Otherwise, returns
-NULL.
-
- SV* gv_const_sv(GV* gv)
-
-=for hackers
-Found in file gv.c
-
-=item gv_fetchmeth
-X<gv_fetchmeth>
-
-Returns the glob with the given C<name> and a defined subroutine or
-C<NULL>. The glob lives in the given C<stash>, or in the stashes
-accessible via @ISA and UNIVERSAL::.
-
-The argument C<level> should be either 0 or -1. If C<level==0>, as a
-side-effect creates a glob with the given C<name> in the given C<stash>
-which in the case of success contains an alias for the subroutine, and sets
-up caching info for this glob.
-
-This function grants C<"SUPER"> token as a postfix of the stash name. The
-GV returned from C<gv_fetchmeth> may be a method cache entry, which is not
-visible to Perl code. So when calling C<call_sv>, you should not use
-the GV directly; instead, you should use the method's CV, which can be
-obtained from the GV with the C<GvCV> macro.
-
- GV* gv_fetchmeth(HV* stash, const char* name, STRLEN len, I32 level)
-
-=for hackers
-Found in file gv.c
-
-=item gv_fetchmethod_autoload
-X<gv_fetchmethod_autoload>
-
-Returns the glob which contains the subroutine to call to invoke the method
-on the C<stash>. In fact in the presence of autoloading this may be the
-glob for "AUTOLOAD". In this case the corresponding variable $AUTOLOAD is
-already setup.
-
-The third parameter of C<gv_fetchmethod_autoload> determines whether
-AUTOLOAD lookup is performed if the given method is not present: non-zero
-means yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD.
-Calling C<gv_fetchmethod> is equivalent to calling C<gv_fetchmethod_autoload>
-with a non-zero C<autoload> parameter.
-
-These functions grant C<"SUPER"> token as a prefix of the method name. Note
-that if you want to keep the returned glob for a long time, you need to
-check for it being "AUTOLOAD", since at the later time the call may load a
-different subroutine due to $AUTOLOAD changing its value. Use the glob
-created via a side effect to do this.
-
-These functions have the same side-effects and as C<gv_fetchmeth> with
-C<level==0>. C<name> should be writable if contains C<':'> or C<'
-''>. The warning against passing the GV returned by C<gv_fetchmeth> to
-C<call_sv> apply equally to these functions.
-
- GV* gv_fetchmethod_autoload(HV* stash, const char* name, I32 autoload)
-
-=for hackers
-Found in file gv.c
-
-=item gv_fetchmeth_autoload
-X<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
-X<gv_stashpv>
-
-Returns a pointer to the stash for a specified package. Uses C<strlen> to
-determine the length of C<name>, then calls C<gv_stashpvn()>.
-
- HV* gv_stashpv(const char* name, I32 flags)
-
-=for hackers
-Found in file gv.c
-
-=item gv_stashpvn
-X<gv_stashpvn>
-
-Returns a pointer to the stash for a specified package. The C<namelen>
-parameter indicates the length of the C<name>, in bytes. C<flags> is passed
-to C<gv_fetchpvn_flags()>, so if set to C<GV_ADD> then the package will be
-created if it does not already exist. If the package does not exist and
-C<flags> is 0 (or any other setting that does not create packages) then NULL
-is returned.
-
-
- HV* gv_stashpvn(const char* name, U32 namelen, I32 flags)
-
-=for hackers
-Found in file gv.c
-
-=item gv_stashpvs
-X<gv_stashpvs>
-
-Like C<gv_stashpvn>, but takes a literal string instead of a string/length pair.
-
- HV* gv_stashpvs(const char* name, I32 create)
-
-=for hackers
-Found in file handy.h
-
-=item gv_stashsv
-X<gv_stashsv>
-
-Returns a pointer to the stash for a specified package. See C<gv_stashpvn>.
-
- HV* gv_stashsv(SV* sv, I32 flags)
-
-=for hackers
-Found in file gv.c
-
-
-=back
-
-=head1 Handy Values
-
-=over 8
-
-=item Nullav
-X<Nullav>
-
-Null AV pointer.
-
-(deprecated - use C<(AV *)NULL> instead)
-
-=for hackers
-Found in file av.h
-
-=item Nullch
-X<Nullch>
-
-Null character pointer. (No longer available when C<PERL_CORE> is defined.)
-
-=for hackers
-Found in file handy.h
-
-=item Nullcv
-X<Nullcv>
-
-Null CV pointer.
-
-(deprecated - use C<(CV *)NULL> instead)
-
-=for hackers
-Found in file cv.h
-
-=item Nullhv
-X<Nullhv>
-
-Null HV pointer.
-
-(deprecated - use C<(HV *)NULL> instead)
-
-=for hackers
-Found in file hv.h
-
-=item Nullsv
-X<Nullsv>
-
-Null SV pointer. (No longer available when C<PERL_CORE> is defined.)
-
-=for hackers
-Found in file handy.h
-
-
-=back
-
-=head1 Hash Manipulation Functions
-
-=over 8
-
-=item get_hv
-X<get_hv>
-
-Returns the HV of the specified Perl hash. C<flags> are passed to
-C<gv_fetchpv>. If C<GV_ADD> is set and the
-Perl variable does not exist then it will be created. If C<flags> is zero
-and the variable does not exist then NULL is returned.
-
-NOTE: the perl_ form of this function is deprecated.
-
- HV* get_hv(const char *name, I32 flags)
-
-=for hackers
-Found in file perl.c
-
-=item HEf_SVKEY
-X<HEf_SVKEY>
-
-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).
-
-=for hackers
-Found in file hv.h
-
-=item HeHASH
-X<HeHASH>
-
-Returns the computed hash stored in the hash entry.
-
- U32 HeHASH(HE* he)
-
-=for hackers
-Found in file hv.h
-
-=item HeKEY
-X<HeKEY>
-
-Returns the actual pointer stored in the key slot of the hash entry. The
-pointer may be either C<char*> or C<SV*>, depending on the value of
-C<HeKLEN()>. Can be assigned to. The C<HePV()> or C<HeSVKEY()> macros are
-usually preferable for finding the value of a key.
-
- void* HeKEY(HE* he)
-
-=for hackers
-Found in file hv.h
-
-=item HeKLEN
-X<HeKLEN>
-
-If this is negative, and amounts to C<HEf_SVKEY>, it indicates the entry
-holds an C<SV*> key. Otherwise, holds the actual length of the key. Can
-be assigned to. The C<HePV()> macro is usually preferable for finding key
-lengths.
-
- STRLEN HeKLEN(HE* he)
-
-=for hackers
-Found in file hv.h
-
-=item HePV
-X<HePV>
-
-Returns the key slot of the hash entry as a C<char*> value, doing any
-necessary dereferencing of possibly C<SV*> keys. The length of the string
-is placed in C<len> (this is a macro, so do I<not> use C<&len>). If you do
-not care about what the length of the key is, you may use the global
-variable C<PL_na>, though this is rather less efficient than using a local
-variable. Remember though, that hash keys in perl are free to contain
-embedded nulls, so using C<strlen()> or similar is not a good way to find
-the length of hash keys. This is very similar to the C<SvPV()> macro
-described elsewhere in this document. See also C<HeUTF8>.
-
-If you are using C<HePV> to get values to pass to C<newSVpvn()> to create a
-new SV, you should consider using C<newSVhek(HeKEY_hek(he))> as it is more
-efficient.
-
- char* HePV(HE* he, STRLEN len)
-
-=for hackers
-Found in file hv.h
-
-=item HeSVKEY
-X<HeSVKEY>
-
-Returns the key as an C<SV*>, or C<NULL> if the hash entry does not
-contain an C<SV*> key.
-
- SV* HeSVKEY(HE* he)
-
-=for hackers
-Found in file hv.h
-
-=item HeSVKEY_force
-X<HeSVKEY_force>
-
-Returns the key as an C<SV*>. Will create and return a temporary mortal
-C<SV*> if the hash entry contains only a C<char*> key.
-
- SV* HeSVKEY_force(HE* he)
-
-=for hackers
-Found in file hv.h
-
-=item HeSVKEY_set
-X<HeSVKEY_set>
-
-Sets the key to a given C<SV*>, taking care to set the appropriate flags to
-indicate the presence of an C<SV*> key, and returns the same
-C<SV*>.
-
- SV* HeSVKEY_set(HE* he, SV* sv)
-
-=for hackers
-Found in file hv.h
-
-=item HeUTF8
-X<HeUTF8>
-
-Returns whether the C<char *> value returned by C<HePV> is encoded in UTF-8,
-doing any necessary dereferencing of possibly C<SV*> keys. The value returned
-will be 0 or non-0, not necessarily 1 (or even a value with any low bits set),
-so B<do not> blindly assign this to a C<bool> variable, as C<bool> may be a
-typedef for C<char>.
-
- char* HeUTF8(HE* he, STRLEN len)
-
-=for hackers
-Found in file hv.h
-
-=item HeVAL
-X<HeVAL>
-
-Returns the value slot (type C<SV*>) stored in the hash entry.
-
- SV* HeVAL(HE* he)
-
-=for hackers
-Found in file hv.h
-
-=item HvNAME
-X<HvNAME>
-
-Returns the package name of a stash, or NULL if C<stash> isn't a stash.
-See C<SvSTASH>, C<CvSTASH>.
-
- char* HvNAME(HV* stash)
-
-=for hackers
-Found in file hv.h
-
-=item hv_assert
-X<hv_assert>
-
-Check that a hash is in an internally consistent state.
-
- void hv_assert(HV *hv)
-
-=for hackers
-Found in file hv.c
-
-=item hv_clear
-X<hv_clear>
-
-Clears a hash, making it empty.
-
- void hv_clear(HV *hv)
-
-=for hackers
-Found in file hv.c
-
-=item hv_clear_placeholders
-X<hv_clear_placeholders>
-
-Clears any placeholders from a hash. If a restricted hash has any of its keys
-marked as readonly and the key is subsequently deleted, the key is not actually
-deleted but is marked by assigning it a value of &PL_sv_placeholder. This tags
-it so it will be ignored by future operations such as iterating over the hash,
-but will still allow the hash to have a value reassigned to the key at some
-future point. This function clears any such placeholder keys from the hash.
-See Hash::Util::lock_keys() for an example of its use.
-
- void hv_clear_placeholders(HV *hv)
-
-=for hackers
-Found in file hv.c
-
-=item hv_delete
-X<hv_delete>
-
-Deletes a key/value pair in the hash. The value SV is removed from the
-hash and returned to the caller. The C<klen> is the length of the key.
-The C<flags> value will normally be zero; if set to G_DISCARD then NULL
-will be returned.
-
- SV* hv_delete(HV *hv, const char *key, I32 klen, I32 flags)
-
-=for hackers
-Found in file hv.c
-
-=item hv_delete_ent
-X<hv_delete_ent>
-
-Deletes a key/value pair in the hash. The value SV is removed from the
-hash and returned to the caller. The C<flags> value will normally be zero;
-if set to G_DISCARD then NULL will be returned. C<hash> can be a valid
-precomputed hash value, or 0 to ask for it to be computed.
-
- SV* hv_delete_ent(HV *hv, SV *keysv, I32 flags, U32 hash)
-
-=for hackers
-Found in file hv.c
-
-=item hv_exists
-X<hv_exists>
-
-Returns a boolean indicating whether the specified hash key exists. The
-C<klen> is the length of the key.
-
- bool hv_exists(HV *hv, const char *key, I32 klen)
-
-=for hackers
-Found in file hv.c
-
-=item hv_exists_ent
-X<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 *hv, SV *keysv, U32 hash)
-
-=for hackers
-Found in file hv.c
-
-=item hv_fetch
-X<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 *hv, const char *key, I32 klen, I32 lval)
-
-=for hackers
-Found in file hv.c
-
-=item hv_fetchs
-X<hv_fetchs>
-
-Like C<hv_fetch>, but takes a literal string instead of a string/length pair.
-
- SV** hv_fetchs(HV* tb, const char* key, I32 lval)
-
-=for hackers
-Found in file handy.h
-
-=item hv_fetch_ent
-X<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 *hv, SV *keysv, I32 lval, U32 hash)
-
-=for hackers
-Found in file hv.c
-
-=item hv_iterinit
-X<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 *hv)
-
-=for hackers
-Found in file hv.c
-
-=item hv_iterkey
-X<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
-X<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
-X<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 *hv)
-
-=for hackers
-Found in file hv.c
-
-=item hv_iternextsv
-X<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
-X<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
-C<&Perl_sv_placeholder>. 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 *hv, I32 flags)
-
-=for hackers
-Found in file hv.c
-
-=item hv_iterval
-X<hv_iterval>
-
-Returns the value from the current position of the hash iterator. See
-C<hv_iterkey>.
-
- SV* hv_iterval(HV *hv, HE *entry)
-
-=for hackers
-Found in file hv.c
-
-=item hv_magic
-X<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_scalar
-X<hv_scalar>
-
-Evaluates the hash in scalar context and returns the result. Handles magic when the hash is tied.
-
- SV* hv_scalar(HV *hv)
-
-=for hackers
-Found in file hv.c
-
-=item hv_store
-X<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. Effectively
-a successful hv_store takes ownership of one reference to C<val>. This is
-usually what you want; a newly created SV has a reference count of one, so
-if all your code does is create SVs then store them in a hash, hv_store
-will own the only reference to the new SV, and your code doesn't need to do
-anything further to tidy up. hv_store is not implemented as a call to
-hv_store_ent, and does not create a temporary SV for the key, so if your
-key data is not already in SV form then use hv_store in preference to
-hv_store_ent.
-
-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 *hv, const char *key, I32 klen, SV *val, U32 hash)
-
-=for hackers
-Found in file hv.c
-
-=item hv_stores
-X<hv_stores>
-
-Like C<hv_store>, but takes a literal string instead of a string/length pair
-and omits the hash parameter.
-
- SV** hv_stores(HV* tb, const char* key, NULLOK SV* val)
-
-=for hackers
-Found in file handy.h
-
-=item hv_store_ent
-X<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. Effectively a successful
-hv_store_ent takes ownership of one reference to C<val>. This is
-usually what you want; a newly created SV has a reference count of one, so
-if all your code does is create SVs then store them in a hash, hv_store
-will own the only reference to the new SV, and your code doesn't need to do
-anything further to tidy up. Note that hv_store_ent only reads the C<key>;
-unlike C<val> it does not take ownership of it, so maintaining the correct
-reference count on C<key> is entirely the caller's responsibility. hv_store
-is not implemented as a call to hv_store_ent, and does not create a temporary
-SV for the key, so if your key data is not already in SV form then use
-hv_store in preference to hv_store_ent.
-
-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 *hv, SV *key, SV *val, U32 hash)
-
-=for hackers
-Found in file hv.c
-
-=item hv_undef
-X<hv_undef>
-
-Undefines the hash.
-
- void hv_undef(HV *hv)
-
-=for hackers
-Found in file hv.c
-
-=item newHV
-X<newHV>
-
-Creates a new HV. The reference count is set to 1.
-
- HV* newHV()
-
-=for hackers
-Found in file hv.h
-
-
-=back
-
-=head1 Magical Functions
-
-=over 8
-
-=item mg_clear
-X<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
-X<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
-X<mg_find>
-
-Finds the magic pointer for type matching the SV. See C<sv_magic>.
-
- MAGIC* mg_find(const SV* sv, int type)
-
-=for hackers
-Found in file mg.c
-
-=item mg_free
-X<mg_free>
-
-Free any magic storage used by the SV. See C<sv_magic>.
-
- int mg_free(SV* sv)
-
-=for hackers
-Found in file mg.c
-
-=item mg_get
-X<mg_get>
-
-Do magic after a value is retrieved from the SV. See C<sv_magic>.
-
- int mg_get(SV* sv)
-
-=for hackers
-Found in file mg.c
-
-=item mg_length
-X<mg_length>
-
-Report on the SV's length. See C<sv_magic>.
-
- U32 mg_length(SV* sv)
-
-=for hackers
-Found in file mg.c
-
-=item mg_magical
-X<mg_magical>
-
-Turns on the magical status of an SV. See C<sv_magic>.
-
- void mg_magical(SV* sv)
-
-=for hackers
-Found in file mg.c
-
-=item mg_set
-X<mg_set>
-
-Do magic after a value is assigned to the SV. See C<sv_magic>.
-
- int mg_set(SV* sv)
-
-=for hackers
-Found in file mg.c
-
-=item SvGETMAGIC
-X<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 SvLOCK
-X<SvLOCK>
-
-Arranges for a mutual exclusion lock to be obtained on sv if a suitable module
-has been loaded.
-
- void SvLOCK(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvSETMAGIC
-X<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
-X<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
-X<SvSetMagicSV_nosteal>
-
-Like C<SvSetSV_nosteal>, but does any set magic required afterwards.
-
- void SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
-
-=for hackers
-Found in file sv.h
-
-=item SvSetSV
-X<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
-X<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 SvSHARE
-X<SvSHARE>
-
-Arranges for sv to be shared between threads if a suitable module
-has been loaded.
-
- void SvSHARE(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvUNLOCK
-X<SvUNLOCK>
-
-Releases a mutual exclusion lock on sv if a suitable module
-has been loaded.
-
- void SvUNLOCK(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-
-=back
-
-=head1 Memory Management
-
-=over 8
-
-=item Copy
-X<Copy>
-
-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>.
-
- void Copy(void* src, void* dest, int nitems, type)
-
-=for hackers
-Found in file handy.h
-
-=item CopyD
-X<CopyD>
-
-Like C<Copy> but returns dest. Useful for encouraging compilers to tail-call
-optimise.
-
- void * CopyD(void* src, void* dest, int nitems, type)
-
-=for hackers
-Found in file handy.h
-
-=item Move
-X<Move>
-
-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>.
-
- void Move(void* src, void* dest, int nitems, type)
-
-=for hackers
-Found in file handy.h
-
-=item MoveD
-X<MoveD>
-
-Like C<Move> but returns dest. Useful for encouraging compilers to tail-call
-optimise.
-
- void * MoveD(void* src, void* dest, int nitems, type)
-
-=for hackers
-Found in file handy.h
-
-=item Newx
-X<Newx>
-
-The XSUB-writer's interface to the C C<malloc> function.
-
-In 5.9.3, Newx() and friends replace the older New() API, and drops
-the first parameter, I<x>, a debug aid which allowed callers to identify
-themselves. This aid has been superseded by a new build option,
-PERL_MEM_LOG (see L<perlhack/PERL_MEM_LOG>). The older API is still
-there for use in XS modules supporting older perls.
-
- void Newx(void* ptr, int nitems, type)
-
-=for hackers
-Found in file handy.h
-
-=item Newxc
-X<Newxc>
-
-The XSUB-writer's interface to the C C<malloc> function, with
-cast. See also C<Newx>.
-
- void Newxc(void* ptr, int nitems, type, cast)
-
-=for hackers
-Found in file handy.h
-
-=item Newxz
-X<Newxz>
-
-The XSUB-writer's interface to the C C<malloc> function. The allocated
-memory is zeroed with C<memzero>. See also C<Newx>.
-
- void Newxz(void* ptr, int nitems, type)
-
-=for hackers
-Found in file handy.h
-
-=item Poison
-X<Poison>
-
-PoisonWith(0xEF) for catching access to freed memory.
-
- void Poison(void* dest, int nitems, type)
-
-=for hackers
-Found in file handy.h
-
-=item PoisonFree
-X<PoisonFree>
-
-PoisonWith(0xEF) for catching access to freed memory.
-
- void PoisonFree(void* dest, int nitems, type)
-
-=for hackers
-Found in file handy.h
-
-=item PoisonNew
-X<PoisonNew>
-
-PoisonWith(0xAB) for catching access to allocated but uninitialized memory.
-
- void PoisonNew(void* dest, int nitems, type)
-
-=for hackers
-Found in file handy.h
-
-=item PoisonWith
-X<PoisonWith>
-
-Fill up memory with a byte pattern (a byte repeated over and over
-again) that hopefully catches attempts to access uninitialized memory.
-
- void PoisonWith(void* dest, int nitems, type, U8 byte)
-
-=for hackers
-Found in file handy.h
-
-=item Renew
-X<Renew>
-
-The XSUB-writer's interface to the C C<realloc> function.
-
- void Renew(void* ptr, int nitems, type)
-
-=for hackers
-Found in file handy.h
-
-=item Renewc
-X<Renewc>
-
-The XSUB-writer's interface to the C C<realloc> function, with
-cast.
-
- void Renewc(void* ptr, int nitems, type, cast)
-
-=for hackers
-Found in file handy.h
-
-=item Safefree
-X<Safefree>
-
-The XSUB-writer's interface to the C C<free> function.
-
- void Safefree(void* ptr)
-
-=for hackers
-Found in file handy.h
-
-=item savepv
-X<savepv>
-
-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.
-
- char* savepv(const char* pv)
-
-=for hackers
-Found in file util.c
-
-=item savepvn
-X<savepvn>
-
-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>, plus a trailing NUL byte. The memory allocated for
-the new string can be freed with the C<Safefree()> function.
-
- char* savepvn(const char* pv, I32 len)
-
-=for hackers
-Found in file util.c
-
-=item savepvs
-X<savepvs>
-
-Like C<savepvn>, but takes a literal string instead of a string/length pair.
-
- char* savepvs(const char* s)
-
-=for hackers
-Found in file handy.h
-
-=item savesharedpv
-X<savesharedpv>
-
-A version of C<savepv()> which allocates the duplicate string in memory
-which is shared between threads.
-
- char* savesharedpv(const char* pv)
-
-=for hackers
-Found in file util.c
-
-=item savesharedpvn
-X<savesharedpvn>
-
-A version of C<savepvn()> which allocates the duplicate string in memory
-which is shared between threads. (With the specific difference that a NULL
-pointer is not acceptable)
-
- char* savesharedpvn(const char *const pv, const STRLEN len)
-
-=for hackers
-Found in file util.c
-
-=item savesvpv
-X<savesvpv>
-
-A version of C<savepv()>/C<savepvn()> which gets the string to duplicate from
-the passed in SV using C<SvPV()>
-
- char* savesvpv(SV* sv)
-
-=for hackers
-Found in file util.c
-
-=item StructCopy
-X<StructCopy>
-
-This is an architecture-independent macro to copy one structure to another.
-
- void StructCopy(type src, type dest, type)
-
-=for hackers
-Found in file handy.h
-
-=item Zero
-X<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.
-
- void Zero(void* dest, int nitems, type)
-
-=for hackers
-Found in file handy.h
-
-=item ZeroD
-X<ZeroD>
-
-Like C<Zero> but returns dest. Useful for encouraging compilers to tail-call
-optimise.
-
- void * ZeroD(void* dest, int nitems, type)
-
-=for hackers
-Found in file handy.h
-
-
-=back
-
-=head1 Miscellaneous Functions
-
-=over 8
-
-=item fbm_compile
-X<fbm_compile>
-
-Analyses the string in order to make fast searches on it using fbm_instr()
--- the Boyer-Moore algorithm.
-
- void fbm_compile(SV* sv, U32 flags)
-
-=for hackers
-Found in file util.c
-
-=item fbm_instr
-X<fbm_instr>
-
-Returns the location of the SV in the string delimited by C<str> and
-C<strend>. It returns C<NULL> 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.
-
- char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlestr, U32 flags)
-
-=for hackers
-Found in file util.c
-
-=item form
-X<form>
-
-Takes a sprintf-style format pattern and conventional
-(non-SV) arguments and returns the formatted string.
-
- (char *) Perl_form(pTHX_ const char* pat, ...)
-
-can be used any place a string (char *) is required:
-
- char * s = Perl_form("%d.%d",major,minor);
-
-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).
-
- char* form(const char* pat, ...)
-
-=for hackers
-Found in file util.c
-
-=item getcwd_sv
-X<getcwd_sv>
-
-Fill the sv with current working directory
-
- int getcwd_sv(SV* sv)
-
-=for hackers
-Found in file util.c
-
-=item my_snprintf
-X<my_snprintf>
-
-The C library C<snprintf> functionality, if available and
-standards-compliant (uses C<vsnprintf>, actually). However, if the
-C<vsnprintf> is not available, will unfortunately use the unsafe
-C<vsprintf> which can overrun the buffer (there is an overrun check,
-but that may be too late). Consider using C<sv_vcatpvf> instead, or
-getting C<vsnprintf>.
-
- int my_snprintf(char *buffer, const Size_t len, const char *format, ...)
-
-=for hackers
-Found in file util.c
-
-=item my_sprintf
-X<my_sprintf>
-
-The C library C<sprintf>, wrapped if necessary, to ensure that it will return
-the length of the string written to the buffer. Only rare pre-ANSI systems
-need the wrapper function - usually this is a direct call to C<sprintf>.
-
- int my_sprintf(char *buffer, const char *pat, ...)
-
-=for hackers
-Found in file util.c
-
-=item my_vsnprintf
-X<my_vsnprintf>
-
-The C library C<vsnprintf> if available and standards-compliant.
-However, if if the C<vsnprintf> is not available, will unfortunately
-use the unsafe C<vsprintf> which can overrun the buffer (there is an
-overrun check, but that may be too late). Consider using
-C<sv_vcatpvf> instead, or getting C<vsnprintf>.
-
- int my_vsnprintf(char *buffer, const Size_t len, const char *format, va_list ap)
-
-=for hackers
-Found in file util.c
-
-=item new_version
-X<new_version>
-
-Returns a new version object based on the passed in SV:
-
- SV *sv = new_version(SV *ver);
-
-Does not alter the passed in ver SV. See "upg_version" if you
-want to upgrade the SV.
-
- SV* new_version(SV *ver)
-
-=for hackers
-Found in file util.c
-
-=item scan_version
-X<scan_version>
-
-Returns a pointer to the next character after the parsed
-version string, as well as upgrading the passed in SV to
-an RV.
-
-Function must be called with an already existing SV like
-
- sv = newSV(0);
- s = scan_version(s, SV *sv, bool qv);
-
-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 an alpha version). The boolean qv denotes that the version
-should be interpreted as if it had multiple decimals, even if
-it doesn't.
-
- const char* scan_version(const char *s, SV *rv, bool qv)
-
-=for hackers
-Found in file util.c
-
-=item strEQ
-X<strEQ>
-
-Test two strings to see if they are equal. Returns true or false.
-
- bool strEQ(char* s1, char* s2)
-
-=for hackers
-Found in file handy.h
-
-=item strGE
-X<strGE>
-
-Test two strings to see if the first, C<s1>, is greater than or equal to
-the second, C<s2>. Returns true or false.
-
- bool strGE(char* s1, char* s2)
-
-=for hackers
-Found in file handy.h
-
-=item strGT
-X<strGT>
-
-Test two strings to see if the first, C<s1>, is greater than the second,
-C<s2>. Returns true or false.
-
- bool strGT(char* s1, char* s2)
-
-=for hackers
-Found in file handy.h
-
-=item strLE
-X<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.
-
- bool strLE(char* s1, char* s2)
-
-=for hackers
-Found in file handy.h
-
-=item strLT
-X<strLT>
-
-Test two strings to see if the first, C<s1>, is less than the second,
-C<s2>. Returns true or false.
-
- bool strLT(char* s1, char* s2)
-
-=for hackers
-Found in file handy.h
-
-=item strNE
-X<strNE>
-
-Test two strings to see if they are different. Returns true or
-false.
-
- bool strNE(char* s1, char* s2)
-
-=for hackers
-Found in file handy.h
-
-=item strnEQ
-X<strnEQ>
-
-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>).
-
- bool strnEQ(char* s1, char* s2, STRLEN len)
-
-=for hackers
-Found in file handy.h
-
-=item strnNE
-X<strnNE>
-
-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>).
-
- bool strnNE(char* s1, char* s2, STRLEN len)
-
-=for hackers
-Found in file handy.h
-
-=item sv_destroyable
-X<sv_destroyable>
-
-Dummy routine which reports that object can be destroyed when there is no
-sharing module present. It ignores its single SV argument, and returns
-'true'. Exists to avoid test for a NULL function pointer and because it
-could potentially warn under some level of strict-ness.
-
- bool sv_destroyable(SV *sv)
-
-=for hackers
-Found in file util.c
-
-=item sv_nosharing
-X<sv_nosharing>
-
-Dummy routine which "shares" an SV when there is no sharing module present.
-Or "locks" it. Or "unlocks" it. In other words, ignores its single SV argument.
-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 *sv)
-
-=for hackers
-Found in file util.c
-
-=item upg_version
-X<upg_version>
-
-In-place upgrade of the supplied SV to a version object.
-
- SV *sv = upg_version(SV *sv, bool qv);
-
-Returns a pointer to the upgraded SV. Set the boolean qv if you want
-to force this SV to be interpreted as an "extended" version.
-
- SV* upg_version(SV *ver, bool qv)
-
-=for hackers
-Found in file util.c
-
-=item vcmp
-X<vcmp>
-
-Version object aware cmp. Both operands must already have been
-converted into version objects.
-
- int vcmp(SV *lhv, SV *rhv)
-
-=for hackers
-Found in file util.c
-
-=item vnormal
-X<vnormal>
-
-Accepts a version object and returns the normalized string
-representation. Call like:
-
- sv = vnormal(rv);
-
-NOTE: you can pass either the object directly or the SV
-contained within the RV.
-
- SV* vnormal(SV *vs)
-
-=for hackers
-Found in file util.c
-
-=item vnumify
-X<vnumify>
-
-Accepts a version object and returns the normalized floating
-point representation. Call like:
-
- sv = vnumify(rv);
-
-NOTE: you can pass either the object directly or the SV
-contained within the RV.
-
- SV* vnumify(SV *vs)
-
-=for hackers
-Found in file util.c
-
-=item vstringify
-X<vstringify>
-
-In order to maintain maximum compatibility with earlier versions
-of Perl, this function will return either the floating point
-notation or the multiple dotted notation, depending on whether
-the original version contained 1 or more dots, respectively
-
- SV* vstringify(SV *vs)
-
-=for hackers
-Found in file util.c
-
-=item vverify
-X<vverify>
-
-Validates that the SV contains a valid version object.
-
- bool vverify(SV *vobj);
-
-Note that it only confirms the bare minimum structure (so as not to get
-confused by derived classes which may contain additional hash entries):
-
- bool vverify(SV *vs)
-
-=for hackers
-Found in file util.c
-
-
-=back
-
-=head1 MRO Functions
-
-=over 8
-
-=item mro_get_linear_isa
-X<mro_get_linear_isa>
-
-Returns either C<mro_get_linear_isa_c3> or
-C<mro_get_linear_isa_dfs> for the given stash,
-dependant upon which MRO is in effect
-for that stash. The return value is a
-read-only AV*.
-
-You are responsible for C<SvREFCNT_inc()> on the
-return value if you plan to store it anywhere
-semi-permanently (otherwise it might be deleted
-out from under you the next time the cache is
-invalidated).
-
- AV* mro_get_linear_isa(HV* stash)
-
-=for hackers
-Found in file mro.c
-
-=item mro_method_changed_in
-X<mro_method_changed_in>
-
-Invalidates method caching on any child classes
-of the given stash, so that they might notice
-the changes in this one.
-
-Ideally, all instances of C<PL_sub_generation++> in
-perl source outside of C<mro.c> should be
-replaced by calls to this.
-
-Perl automatically handles most of the common
-ways a method might be redefined. However, there
-are a few ways you could change a method in a stash
-without the cache code noticing, in which case you
-need to call this method afterwards:
-
-1) Directly manipulating the stash HV entries from
-XS code.
-
-2) Assigning a reference to a readonly scalar
-constant into a stash entry in order to create
-a constant subroutine (like constant.pm
-does).
-
-This same method is available from pure perl
-via, C<mro::method_changed_in(classname)>.
-
- void mro_method_changed_in(HV* stash)
-
-=for hackers
-Found in file mro.c
-
-
-=back
-
-=head1 Multicall Functions
-
-=over 8
-
-=item dMULTICALL
-X<dMULTICALL>
-
-Declare local variables for a multicall. See L<perlcall/Lightweight Callbacks>.
-
- dMULTICALL;
-
-=for hackers
-Found in file cop.h
-
-=item MULTICALL
-X<MULTICALL>
-
-Make a lightweight callback. See L<perlcall/Lightweight Callbacks>.
-
- MULTICALL;
-
-=for hackers
-Found in file cop.h
-
-=item POP_MULTICALL
-X<POP_MULTICALL>
-
-Closing bracket for a lightweight callback.
-See L<perlcall/Lightweight Callbacks>.
-
- POP_MULTICALL;
-
-=for hackers
-Found in file cop.h
-
-=item PUSH_MULTICALL
-X<PUSH_MULTICALL>
-
-Opening bracket for a lightweight callback.
-See L<perlcall/Lightweight Callbacks>.
-
- PUSH_MULTICALL;
-
-=for hackers
-Found in file cop.h
-
-
-=back
-
-=head1 Numeric functions
-
-=over 8
-
-=item grok_bin
-X<grok_bin>
-
-converts a string representing a binary number to numeric form.
-
-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.
-Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
-invalid character will also trigger a warning.
-On return I<*len> is set to the length of the scanned string,
-and I<*flags> gives output flags.
-
-If the value is <= C<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 binary 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(const char* start, STRLEN* len_p, I32* flags, NV *result)
-
-=for hackers
-Found in file numeric.c
-
-=item grok_hex
-X<grok_hex>
-
-converts a string representing a hex number to numeric form.
-
-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.
-Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
-invalid character will also trigger a warning.
-On return I<*len> is set to the length of the 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(const char* start, STRLEN* len_p, I32* flags, NV *result)
-
-=for hackers
-Found in file numeric.c
-
-=item grok_number
-X<grok_number>
-
-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).
-
-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 numeric.c
-
-=item grok_numeric_radix
-X<grok_numeric_radix>
-
-Scan and skip for a numeric decimal separator (radix).
-
- bool grok_numeric_radix(const char **sp, const char *send)
-
-=for hackers
-Found in file numeric.c
-
-=item grok_oct
-X<grok_oct>
-
-converts a string representing an octal number to numeric form.
-
-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.
-Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
-invalid character will also trigger a warning.
-On return I<*len> is set to the length of the 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_oct>
-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).
-
-If C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the octal
-number may use '_' characters to separate digits.
-
- UV grok_oct(const char* start, STRLEN* len_p, I32* flags, NV *result)
-
-=for hackers
-Found in file numeric.c
-
-=item Perl_signbit
-X<Perl_signbit>
-
-Return a non-zero integer if the sign bit on an NV is set, and 0 if
-it is not.
-
-If Configure detects this system has a signbit() that will work with
-our NVs, then we just use it via the #define in perl.h. Otherwise,
-fall back on this implementation. As a first pass, this gets everything
-right except -0.0. Alas, catching -0.0 is the main use for this function,
-so this is not too helpful yet. Still, at least we have the scaffolding
-in place to support other systems, should that prove useful.
-
-
-Configure notes: This function is called 'Perl_signbit' instead of a
-plain 'signbit' because it is easy to imagine a system having a signbit()
-function or macro that doesn't happen to work with our particular choice
-of NVs. We shouldn't just re-#define signbit as Perl_signbit and expect
-the standard system headers to be happy. Also, this is a no-context
-function (no pTHX_) because Perl_signbit() is usually re-#defined in
-perl.h as a simple macro call to the system's signbit().
-Users should just always call Perl_signbit().
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- int Perl_signbit(NV f)
-
-=for hackers
-Found in file numeric.c
-
-=item scan_bin
-X<scan_bin>
-
-For backwards compatibility. Use C<grok_bin> instead.
-
- NV scan_bin(const char* start, STRLEN len, STRLEN* retlen)
-
-=for hackers
-Found in file numeric.c
-
-=item scan_hex
-X<scan_hex>
-
-For backwards compatibility. Use C<grok_hex> instead.
-
- NV scan_hex(const char* start, STRLEN len, STRLEN* retlen)
-
-=for hackers
-Found in file numeric.c
-
-=item scan_oct
-X<scan_oct>
-
-For backwards compatibility. Use C<grok_oct> instead.
-
- NV scan_oct(const char* start, STRLEN len, STRLEN* retlen)
-
-=for hackers
-Found in file numeric.c
-
-
-=back
-
-=head1 Optree Manipulation Functions
-
-=over 8
-
-=item cv_const_sv
-X<cv_const_sv>
-
-If C<cv> is a constant sub eligible for inlining. returns the constant
-value returned by the sub. Otherwise, returns NULL.
-
-Constant subs can be created with C<newCONSTSUB> or as described in
-L<perlsub/"Constant Functions">.
-
- SV* cv_const_sv(const CV *const cv)
-
-=for hackers
-Found in file op.c
-
-=item newCONSTSUB
-X<newCONSTSUB>
-
-Creates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is
-eligible for inlining at compile-time.
-
-Passing NULL for SV creates a constant sub equivalent to C<sub BAR () {}>,
-which won't be called if used as a destructor, but will suppress the overhead
-of a call to C<AUTOLOAD>. (This form, however, isn't eligible for inlining at
-compile time.)
-
- CV* newCONSTSUB(HV* stash, const char* name, SV* sv)
-
-=for hackers
-Found in file op.c
-
-=item newXS
-X<newXS>
-
-Used by C<xsubpp> to hook up XSUBs as Perl subs. I<filename> needs to be
-static storage, as it is used directly as CvFILE(), without a copy being made.
-
-=for hackers
-Found in file op.c
-
-
-=back
-
-=head1 Pad Data Structures
-
-=over 8
-
-=item pad_sv
-X<pad_sv>
-
-Get the value at offset po in the current pad.
-Use macro PAD_SV instead of calling this function directly.
-
- SV* pad_sv(PADOFFSET po)
-
-=for hackers
-Found in file pad.c
-
-
-=back
-
-=head1 Per-Interpreter Variables
-
-=over 8
-
-=item PL_modglobal
-X<PL_modglobal>
-
-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.
-
- HV* PL_modglobal
-
-=for hackers
-Found in file intrpvar.h
-
-=item PL_na
-X<PL_na>
-
-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.
-
- STRLEN PL_na
-
-=for hackers
-Found in file intrpvar.h
-
-=item PL_sv_no
-X<PL_sv_no>
-
-This is the C<false> SV. See C<PL_sv_yes>. Always refer to this as
-C<&PL_sv_no>.
-
- SV PL_sv_no
-
-=for hackers
-Found in file intrpvar.h
-
-=item PL_sv_undef
-X<PL_sv_undef>
-
-This is the C<undef> SV. Always refer to this as C<&PL_sv_undef>.
-
- SV PL_sv_undef
-
-=for hackers
-Found in file intrpvar.h
-
-=item PL_sv_yes
-X<PL_sv_yes>
-
-This is the C<true> SV. See C<PL_sv_no>. Always refer to this as
-C<&PL_sv_yes>.
-
- SV PL_sv_yes
-
-=for hackers
-Found in file intrpvar.h
-
-
-=back
-
-=head1 REGEXP Functions
-
-=over 8
-
-=item SvRX
-X<SvRX>
-
-Convenience macro to get the REGEXP from a SV. This is approximately
-equivalent to the following snippet:
-
- if (SvMAGICAL(sv))
- mg_get(sv);
- if (SvROK(sv) &&
- (tmpsv = (SV*)SvRV(sv)) &&
- SvTYPE(tmpsv) == SVt_PVMG &&
- (tmpmg = mg_find(tmpsv, PERL_MAGIC_qr)))
- {
- return (REGEXP *)tmpmg->mg_obj;
- }
-
-NULL will be returned if a REGEXP* is not found.
-
- REGEXP * SvRX(SV *sv)
-
-=for hackers
-Found in file regexp.h
-
-=item SvRXOK
-X<SvRXOK>
-
-Returns a boolean indicating whether the SV contains qr magic
-(PERL_MAGIC_qr).
-
-If you want to do something with the REGEXP* later use SvRX instead
-and check for NULL.
-
- bool SvRXOK(SV* sv)
-
-=for hackers
-Found in file regexp.h
-
-
-=back
-
-=head1 Simple Exception Handling Macros
-
-=over 8
-
-=item dXCPT
-X<dXCPT>
-
-Set up necessary local variables for exception handling.
-See L<perlguts/"Exception Handling">.
-
- dXCPT;
-
-=for hackers
-Found in file XSUB.h
-
-=item XCPT_CATCH
-X<XCPT_CATCH>
-
-Introduces a catch block. See L<perlguts/"Exception Handling">.
-
-=for hackers
-Found in file XSUB.h
-
-=item XCPT_RETHROW
-X<XCPT_RETHROW>
-
-Rethrows a previously caught exception. See L<perlguts/"Exception Handling">.
-
- XCPT_RETHROW;
-
-=for hackers
-Found in file XSUB.h
-
-=item XCPT_TRY_END
-X<XCPT_TRY_END>
-
-Ends a try block. See L<perlguts/"Exception Handling">.
-
-=for hackers
-Found in file XSUB.h
-
-=item XCPT_TRY_START
-X<XCPT_TRY_START>
-
-Starts a try block. See L<perlguts/"Exception Handling">.
-
-=for hackers
-Found in file XSUB.h
-
-
-=back
-
-=head1 Stack Manipulation Macros
-
-=over 8
-
-=item dMARK
-X<dMARK>
-
-Declare a stack marker variable, C<mark>, for the XSUB. See C<MARK> and
-C<dORIGMARK>.
-
- dMARK;
-
-=for hackers
-Found in file pp.h
-
-=item dORIGMARK
-X<dORIGMARK>
-
-Saves the original stack mark for the XSUB. See C<ORIGMARK>.
-
- dORIGMARK;
-
-=for hackers
-Found in file pp.h
-
-=item dSP
-X<dSP>
-
-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 pp.h
-
-=item EXTEND
-X<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.
-
- void EXTEND(SP, int nitems)
-
-=for hackers
-Found in file pp.h
-
-=item MARK
-X<MARK>
-
-Stack marker variable for the XSUB. See C<dMARK>.
-
-=for hackers
-Found in file pp.h
-
-=item mPUSHi
-X<mPUSHi>
-
-Push an integer onto the stack. The stack must have room for this element.
-Does not use C<TARG>. See also C<PUSHi>, C<mXPUSHi> and C<XPUSHi>.
-
- void mPUSHi(IV iv)
-
-=for hackers
-Found in file pp.h
-
-=item mPUSHn
-X<mPUSHn>
-
-Push a double onto the stack. The stack must have room for this element.
-Does not use C<TARG>. See also C<PUSHn>, C<mXPUSHn> and C<XPUSHn>.
-
- void mPUSHn(NV nv)
-
-=for hackers
-Found in file pp.h
-
-=item mPUSHp
-X<mPUSHp>
-
-Push a string onto the stack. The stack must have room for this element.
-The C<len> indicates the length of the string. Does not use C<TARG>.
-See also C<PUSHp>, C<mXPUSHp> and C<XPUSHp>.
-
- void mPUSHp(char* str, STRLEN len)
-
-=for hackers
-Found in file pp.h
-
-=item mPUSHs
-X<mPUSHs>
-
-Push an SV onto the stack and mortalizes the SV. The stack must have room
-for this element. Does not use C<TARG>. See also C<PUSHs> and C<mXPUSHs>.
-
- void mPUSHs(SV* sv)
-
-=for hackers
-Found in file pp.h
-
-=item mPUSHu
-X<mPUSHu>
-
-Push an unsigned integer onto the stack. The stack must have room for this
-element. Does not use C<TARG>. See also C<PUSHu>, C<mXPUSHu> and C<XPUSHu>.
-
- void mPUSHu(UV uv)
-
-=for hackers
-Found in file pp.h
-
-=item mXPUSHi
-X<mXPUSHi>
-
-Push an integer onto the stack, extending the stack if necessary.
-Does not use C<TARG>. See also C<XPUSHi>, C<mPUSHi> and C<PUSHi>.
-
- void mXPUSHi(IV iv)
-
-=for hackers
-Found in file pp.h
-
-=item mXPUSHn
-X<mXPUSHn>
-
-Push a double onto the stack, extending the stack if necessary.
-Does not use C<TARG>. See also C<XPUSHn>, C<mPUSHn> and C<PUSHn>.
-
- void mXPUSHn(NV nv)
-
-=for hackers
-Found in file pp.h
-
-=item mXPUSHp
-X<mXPUSHp>
-
-Push a string onto the stack, extending the stack if necessary. The C<len>
-indicates the length of the string. Does not use C<TARG>. See also C<XPUSHp>,
-C<mPUSHp> and C<PUSHp>.
-
- void mXPUSHp(char* str, STRLEN len)
-
-=for hackers
-Found in file pp.h
-
-=item mXPUSHs
-X<mXPUSHs>
-
-Push an SV onto the stack, extending the stack if necessary and mortalizes
-the SV. Does not use C<TARG>. See also C<XPUSHs> and C<mPUSHs>.
-
- void mXPUSHs(SV* sv)
-
-=for hackers
-Found in file pp.h
-
-=item mXPUSHu
-X<mXPUSHu>
-
-Push an unsigned integer onto the stack, extending the stack if necessary.
-Does not use C<TARG>. See also C<XPUSHu>, C<mPUSHu> and C<PUSHu>.
-
- void mXPUSHu(UV uv)
-
-=for hackers
-Found in file pp.h
-
-=item ORIGMARK
-X<ORIGMARK>
-
-The original stack mark for the XSUB. See C<dORIGMARK>.
-
-=for hackers
-Found in file pp.h
-
-=item POPi
-X<POPi>
-
-Pops an integer off the stack.
-
- IV POPi
-
-=for hackers
-Found in file pp.h
-
-=item POPl
-X<POPl>
-
-Pops a long off the stack.
-
- long POPl
-
-=for hackers
-Found in file pp.h
-
-=item POPn
-X<POPn>
-
-Pops a double off the stack.
-
- NV POPn
-
-=for hackers
-Found in file pp.h
-
-=item POPp
-X<POPp>
-
-Pops a string off the stack. Deprecated. New code should use POPpx.
-
- char* POPp
-
-=for hackers
-Found in file pp.h
-
-=item POPpbytex
-X<POPpbytex>
-
-Pops a string off the stack which must consist of bytes i.e. characters < 256.
-
- char* POPpbytex
-
-=for hackers
-Found in file pp.h
-
-=item POPpx
-X<POPpx>
-
-Pops a string off the stack.
-
- char* POPpx
-
-=for hackers
-Found in file pp.h
-
-=item POPs
-X<POPs>
-
-Pops an SV off the stack.
-
- SV* POPs
-
-=for hackers
-Found in file pp.h
-
-=item PUSHi
-X<PUSHi>
-
-Push an integer onto the stack. The stack must have room for this element.
-Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
-called to declare it. Do not call multiple C<TARG>-oriented macros to
-return lists from XSUB's - see C<mPUSHi> instead. See also C<XPUSHi> and
-C<mXPUSHi>.
-
- void PUSHi(IV iv)
-
-=for hackers
-Found in file pp.h
-
-=item PUSHMARK
-X<PUSHMARK>
-
-Opening bracket for arguments on a callback. See C<PUTBACK> and
-L<perlcall>.
-
- void PUSHMARK(SP)
-
-=for hackers
-Found in file pp.h
-
-=item PUSHmortal
-X<PUSHmortal>
-
-Push a new mortal SV onto the stack. The stack must have room for this
-element. Does not use C<TARG>. See also C<PUSHs>, C<XPUSHmortal> and C<XPUSHs>.
-
- void PUSHmortal()
-
-=for hackers
-Found in file pp.h
-
-=item PUSHn
-X<PUSHn>
-
-Push a double onto the stack. The stack must have room for this element.
-Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
-called to declare it. Do not call multiple C<TARG>-oriented macros to
-return lists from XSUB's - see C<mPUSHn> instead. See also C<XPUSHn> and
-C<mXPUSHn>.
-
- void PUSHn(NV nv)
-
-=for hackers
-Found in file pp.h
-
-=item PUSHp
-X<PUSHp>
-
-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. Uses
-C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to declare it. Do not
-call multiple C<TARG>-oriented macros to return lists from XSUB's - see
-C<mPUSHp> instead. See also C<XPUSHp> and C<mXPUSHp>.
-
- void PUSHp(char* str, STRLEN len)
-
-=for hackers
-Found in file pp.h
-
-=item PUSHs
-X<PUSHs>
-
-Push an SV onto the stack. The stack must have room for this element.
-Does not handle 'set' magic. Does not use C<TARG>. See also C<PUSHmortal>,
-C<XPUSHs> and C<XPUSHmortal>.
-
- void PUSHs(SV* sv)
-
-=for hackers
-Found in file pp.h
-
-=item PUSHu
-X<PUSHu>
-
-Push an unsigned integer onto the stack. The stack must have room for this
-element. Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG>
-should be called to declare it. Do not call multiple C<TARG>-oriented
-macros to return lists from XSUB's - see C<mPUSHu> instead. See also
-C<XPUSHu> and C<mXPUSHu>.
-
- void PUSHu(UV uv)
-
-=for hackers
-Found in file pp.h
-
-=item PUTBACK
-X<PUTBACK>
-
-Closing bracket for XSUB arguments. This is usually handled by C<xsubpp>.
-See C<PUSHMARK> and L<perlcall> for other uses.
-
- PUTBACK;
-
-=for hackers
-Found in file pp.h
-
-=item SP
-X<SP>
-
-Stack pointer. This is usually handled by C<xsubpp>. See C<dSP> and
-C<SPAGAIN>.
-
-=for hackers
-Found in file pp.h
-
-=item SPAGAIN
-X<SPAGAIN>
-
-Refetch the stack pointer. Used after a callback. See L<perlcall>.
-
- SPAGAIN;
-
-=for hackers
-Found in file pp.h
-
-=item XPUSHi
-X<XPUSHi>
-
-Push an integer onto the stack, extending the stack if necessary. Handles
-'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to
-declare it. Do not call multiple C<TARG>-oriented macros to return lists
-from XSUB's - see C<mXPUSHi> instead. See also C<PUSHi> and C<mPUSHi>.
-
- void XPUSHi(IV iv)
-
-=for hackers
-Found in file pp.h
-
-=item XPUSHmortal
-X<XPUSHmortal>
-
-Push a new mortal SV onto the stack, extending the stack if necessary.
-Does not use C<TARG>. See also C<XPUSHs>, C<PUSHmortal> and C<PUSHs>.
-
- void XPUSHmortal()
-
-=for hackers
-Found in file pp.h
-
-=item XPUSHn
-X<XPUSHn>
-
-Push a double onto the stack, extending the stack if necessary. Handles
-'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to
-declare it. Do not call multiple C<TARG>-oriented macros to return lists
-from XSUB's - see C<mXPUSHn> instead. See also C<PUSHn> and C<mPUSHn>.
-
- void XPUSHn(NV nv)
-
-=for hackers
-Found in file pp.h
-
-=item XPUSHp
-X<XPUSHp>
-
-Push a string onto the stack, extending the stack if necessary. The C<len>
-indicates the length of the string. Handles 'set' magic. Uses C<TARG>, so
-C<dTARGET> or C<dXSTARG> should be called to declare it. Do not call
-multiple C<TARG>-oriented macros to return lists from XSUB's - see
-C<mXPUSHp> instead. See also C<PUSHp> and C<mPUSHp>.
-
- void XPUSHp(char* str, STRLEN len)
-
-=for hackers
-Found in file pp.h
-
-=item XPUSHs
-X<XPUSHs>
-
-Push an SV onto the stack, extending the stack if necessary. Does not
-handle 'set' magic. Does not use C<TARG>. See also C<XPUSHmortal>,
-C<PUSHs> and C<PUSHmortal>.
-
- void XPUSHs(SV* sv)
-
-=for hackers
-Found in file pp.h
-
-=item XPUSHu
-X<XPUSHu>
-
-Push an unsigned integer onto the stack, extending the stack if necessary.
-Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
-called to declare it. Do not call multiple C<TARG>-oriented macros to
-return lists from XSUB's - see C<mXPUSHu> instead. See also C<PUSHu> and
-C<mPUSHu>.
-
- void XPUSHu(UV uv)
-
-=for hackers
-Found in file pp.h
-
-=item XSRETURN
-X<XSRETURN>
-
-Return from XSUB, indicating number of items on the stack. This is usually
-handled by C<xsubpp>.
-
- void XSRETURN(int nitems)
-
-=for hackers
-Found in file XSUB.h
-
-=item XSRETURN_EMPTY
-X<XSRETURN_EMPTY>
-
-Return an empty list from an XSUB immediately.
-
- XSRETURN_EMPTY;
-
-=for hackers
-Found in file XSUB.h
-
-=item XSRETURN_IV
-X<XSRETURN_IV>
-
-Return an integer from an XSUB immediately. Uses C<XST_mIV>.
-
- void XSRETURN_IV(IV iv)
-
-=for hackers
-Found in file XSUB.h
-
-=item XSRETURN_NO
-X<XSRETURN_NO>
-
-Return C<&PL_sv_no> from an XSUB immediately. Uses C<XST_mNO>.
-
- XSRETURN_NO;
-
-=for hackers
-Found in file XSUB.h
-
-=item XSRETURN_NV
-X<XSRETURN_NV>
-
-Return a double from an XSUB immediately. Uses C<XST_mNV>.
-
- void XSRETURN_NV(NV nv)
-
-=for hackers
-Found in file XSUB.h
-
-=item XSRETURN_PV
-X<XSRETURN_PV>
-
-Return a copy of a string from an XSUB immediately. Uses C<XST_mPV>.
-
- void XSRETURN_PV(char* str)
-
-=for hackers
-Found in file XSUB.h
-
-=item XSRETURN_UNDEF
-X<XSRETURN_UNDEF>
-
-Return C<&PL_sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>.
-
- XSRETURN_UNDEF;
-
-=for hackers
-Found in file XSUB.h
-
-=item XSRETURN_UV
-X<XSRETURN_UV>
-
-Return an integer from an XSUB immediately. Uses C<XST_mUV>.
-
- void XSRETURN_UV(IV uv)
-
-=for hackers
-Found in file XSUB.h
-
-=item XSRETURN_YES
-X<XSRETURN_YES>
-
-Return C<&PL_sv_yes> from an XSUB immediately. Uses C<XST_mYES>.
-
- XSRETURN_YES;
-
-=for hackers
-Found in file XSUB.h
-
-=item XST_mIV
-X<XST_mIV>
-
-Place an integer into the specified position C<pos> on the stack. The
-value is stored in a new mortal SV.
-
- void XST_mIV(int pos, IV iv)
-
-=for hackers
-Found in file XSUB.h
-
-=item XST_mNO
-X<XST_mNO>
-
-Place C<&PL_sv_no> into the specified position C<pos> on the
-stack.
-
- void XST_mNO(int pos)
-
-=for hackers
-Found in file XSUB.h
-
-=item XST_mNV
-X<XST_mNV>
-
-Place a double into the specified position C<pos> on the stack. The value
-is stored in a new mortal SV.
-
- void XST_mNV(int pos, NV nv)
-
-=for hackers
-Found in file XSUB.h
-
-=item XST_mPV
-X<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.
-
- void XST_mPV(int pos, char* str)
-
-=for hackers
-Found in file XSUB.h
-
-=item XST_mUNDEF
-X<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 XST_mYES
-X<XST_mYES>
-
-Place C<&PL_sv_yes> into the specified position C<pos> on the
-stack.
-
- void XST_mYES(int pos)
-
-=for hackers
-Found in file XSUB.h
-
-
-=back
-
-=head1 SV Flags
-
-=over 8
-
-=item svtype
-X<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 SVt_IV
-X<SVt_IV>
-
-Integer type flag for scalars. See C<svtype>.
-
-=for hackers
-Found in file sv.h
-
-=item SVt_NV
-X<SVt_NV>
-
-Double type flag for scalars. See C<svtype>.
-
-=for hackers
-Found in file sv.h
-
-=item SVt_PV
-X<SVt_PV>
-
-Pointer type flag for scalars. See C<svtype>.
-
-=for hackers
-Found in file sv.h
-
-=item SVt_PVAV
-X<SVt_PVAV>
-
-Type flag for arrays. See C<svtype>.
-
-=for hackers
-Found in file sv.h
-
-=item SVt_PVCV
-X<SVt_PVCV>
-
-Type flag for code refs. See C<svtype>.
-
-=for hackers
-Found in file sv.h
-
-=item SVt_PVHV
-X<SVt_PVHV>
-
-Type flag for hashes. See C<svtype>.
-
-=for hackers
-Found in file sv.h
-
-=item SVt_PVMG
-X<SVt_PVMG>
-
-Type flag for blessed scalars. See C<svtype>.
-
-=for hackers
-Found in file sv.h
-
-
-=back
-
-=head1 SV Manipulation Functions
-
-=over 8
-
-=item croak_xs_usage
-X<croak_xs_usage>
-
-A specialised variant of C<croak()> for emitting the usage message for xsubs
-
- croak_xs_usage(cv, "eee_yow");
-
-works out the package name and subroutine name from C<cv>, and then calls
-C<croak()>. Hence if C<cv> is C<&ouch::awk>, it would call C<croak> as:
-
- Perl_croak(aTHX_ "Usage %s::%s(%s)", "ouch" "awk", "eee_yow");
-
- void croak_xs_usage(const CV *const cv, const char *const params)
-
-=for hackers
-Found in file universal.c
-
-=item get_sv
-X<get_sv>
-
-Returns the SV of the specified Perl scalar. C<flags> are passed to
-C<gv_fetchpv>. If C<GV_ADD> is set and the
-Perl variable does not exist then it will be created. If C<flags> is zero
-and the variable does not exist then NULL is returned.
-
-NOTE: the perl_ form of this function is deprecated.
-
- SV* get_sv(const char *name, I32 flags)
-
-=for hackers
-Found in file perl.c
-
-=item newRV_inc
-X<newRV_inc>
-
-Creates an RV wrapper for an SV. The reference count for the original SV is
-incremented.
-
- SV* newRV_inc(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item newSVpvn_utf8
-X<newSVpvn_utf8>
-
-Creates a new SV and copies a string into it. If utf8 is true, calls
-C<SvUTF8_on> on the new SV. Implemented as a wrapper around C<newSVpvn_flags>.
-
- SV* newSVpvn_utf8(NULLOK const char* s, STRLEN len, U32 utf8)
-
-=for hackers
-Found in file sv.h
-
-=item SvCUR
-X<SvCUR>
-
-Returns the length of the string which is in the SV. See C<SvLEN>.
-
- STRLEN SvCUR(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvCUR_set
-X<SvCUR_set>
-
-Set the current length of the string which is in the SV. See C<SvCUR>
-and C<SvIV_set>.
-
- void SvCUR_set(SV* sv, STRLEN len)
-
-=for hackers
-Found in file sv.h
-
-=item SvEND
-X<SvEND>
-
-Returns a pointer to the last character in the string which is in the SV.
-See C<SvCUR>. Access the character as *(SvEND(sv)).
-
- char* SvEND(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvGAMAGIC
-X<SvGAMAGIC>
-
-Returns true if the SV has get magic or overloading. If either is true then
-the scalar is active data, and has the potential to return a new value every
-time it is accessed. Hence you must be careful to only read it once per user
-logical operation and work with that returned value. If neither is true then
-the scalar's value cannot change unless written to.
-
- char* SvGAMAGIC(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvGROW
-X<SvGROW>
-
-Expands the character buffer in the SV so that it has room for the
-indicated number of bytes (remember to reserve space for an extra trailing
-NUL character). Calls C<sv_grow> to perform the expansion if necessary.
-Returns a pointer to the character buffer.
-
- char * SvGROW(SV* sv, STRLEN len)
-
-=for hackers
-Found in file sv.h
-
-=item SvIOK
-X<SvIOK>
-
-Returns a U32 value indicating whether the SV contains an integer.
-
- U32 SvIOK(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvIOKp
-X<SvIOKp>
-
-Returns a U32 value indicating whether the SV contains an integer. Checks
-the B<private> setting. Use C<SvIOK> instead.
-
- U32 SvIOKp(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvIOK_notUV
-X<SvIOK_notUV>
-
-Returns a boolean indicating whether the SV contains a signed integer.
-
- bool SvIOK_notUV(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvIOK_off
-X<SvIOK_off>
-
-Unsets the IV status of an SV.
-
- void SvIOK_off(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvIOK_on
-X<SvIOK_on>
-
-Tells an SV that it is an integer.
-
- void SvIOK_on(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvIOK_only
-X<SvIOK_only>
-
-Tells an SV that it is an integer and disables all other OK bits.
-
- void SvIOK_only(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvIOK_only_UV
-X<SvIOK_only_UV>
-
-Tells and SV that it is an unsigned integer and disables all other OK bits.
-
- void SvIOK_only_UV(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvIOK_UV
-X<SvIOK_UV>
-
-Returns a boolean indicating whether the SV contains an unsigned integer.
-
- bool SvIOK_UV(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvIsCOW
-X<SvIsCOW>
-
-Returns a boolean indicating whether the SV is Copy-On-Write. (either shared
-hash key scalars, or full Copy On Write scalars if 5.9.0 is configured for
-COW)
-
- bool SvIsCOW(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvIsCOW_shared_hash
-X<SvIsCOW_shared_hash>
-
-Returns a boolean indicating whether the SV is Copy-On-Write shared hash key
-scalar.
-
- bool SvIsCOW_shared_hash(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvIV
-X<SvIV>
-
-Coerces the given SV to an integer and returns it. See C<SvIVx> for a
-version which guarantees to evaluate sv only once.
-
- IV SvIV(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvIVX
-X<SvIVX>
-
-Returns the raw value in the SV's IV slot, without checks or conversions.
-Only use when you are sure SvIOK is true. See also C<SvIV()>.
-
- IV SvIVX(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvIVx
-X<SvIVx>
-
-Coerces the given SV to an integer and returns it. Guarantees to evaluate
-C<sv> only once. Only use this if C<sv> is an expression with side effects,
-otherwise use the more efficient C<SvIV>.
-
- IV SvIVx(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvIV_nomg
-X<SvIV_nomg>
-
-Like C<SvIV> but doesn't process magic.
-
- IV SvIV_nomg(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvIV_set
-X<SvIV_set>
-
-Set the value of the IV pointer in sv to val. It is possible to perform
-the same function of this macro with an lvalue assignment to C<SvIVX>.
-With future Perls, however, it will be more efficient to use
-C<SvIV_set> instead of the lvalue assignment to C<SvIVX>.
-
- void SvIV_set(SV* sv, IV val)
-
-=for hackers
-Found in file sv.h
-
-=item SvLEN
-X<SvLEN>
-
-Returns the size of the string buffer in the SV, not including any part
-attributable to C<SvOOK>. See C<SvCUR>.
-
- STRLEN SvLEN(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvLEN_set
-X<SvLEN_set>
-
-Set the actual length of the string which is in the SV. See C<SvIV_set>.
-
- void SvLEN_set(SV* sv, STRLEN len)
-
-=for hackers
-Found in file sv.h
-
-=item SvMAGIC_set
-X<SvMAGIC_set>
-
-Set the value of the MAGIC pointer in sv to val. See C<SvIV_set>.
-
- void SvMAGIC_set(SV* sv, MAGIC* val)
-
-=for hackers
-Found in file sv.h
-
-=item SvNIOK
-X<SvNIOK>
-
-Returns a U32 value indicating whether the SV contains a number, integer or
-double.
-
- U32 SvNIOK(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvNIOKp
-X<SvNIOKp>
-
-Returns a U32 value indicating whether the SV contains a number, integer or
-double. Checks the B<private> setting. Use C<SvNIOK> instead.
-
- U32 SvNIOKp(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvNIOK_off
-X<SvNIOK_off>
-
-Unsets the NV/IV status of an SV.
-
- void SvNIOK_off(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvNOK
-X<SvNOK>
-
-Returns a U32 value indicating whether the SV contains a double.
-
- U32 SvNOK(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvNOKp
-X<SvNOKp>
-
-Returns a U32 value indicating whether the SV contains a double. Checks the
-B<private> setting. Use C<SvNOK> instead.
-
- U32 SvNOKp(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvNOK_off
-X<SvNOK_off>
-
-Unsets the NV status of an SV.
-
- void SvNOK_off(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvNOK_on
-X<SvNOK_on>
-
-Tells an SV that it is a double.
-
- void SvNOK_on(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvNOK_only
-X<SvNOK_only>
-
-Tells an SV that it is a double and disables all other OK bits.
-
- void SvNOK_only(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvNV
-X<SvNV>
-
-Coerce the given SV to a double and return it. See C<SvNVx> for a version
-which guarantees to evaluate sv only once.
-
- NV SvNV(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvNVX
-X<SvNVX>
-
-Returns the raw value in the SV's NV slot, without checks or conversions.
-Only use when you are sure SvNOK is true. See also C<SvNV()>.
-
- NV SvNVX(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvNVx
-X<SvNVx>
-
-Coerces the given SV to a double and returns it. Guarantees to evaluate
-C<sv> only once. Only use this if C<sv> is an expression with side effects,
-otherwise use the more efficient C<SvNV>.
-
- NV SvNVx(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvNV_set
-X<SvNV_set>
-
-Set the value of the NV pointer in sv to val. See C<SvIV_set>.
-
- void SvNV_set(SV* sv, NV val)
-
-=for hackers
-Found in file sv.h
-
-=item SvOK
-X<SvOK>
-
-Returns a U32 value indicating whether the value is an SV. It also tells
-whether the value is defined or not.
-
- U32 SvOK(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvOOK
-X<SvOOK>
-
-Returns a U32 indicating whether the pointer to the string buffer is offset.
-This hack is used internally to speed up removal of characters from the
-beginning of a SvPV. When SvOOK is true, then the start of the
-allocated string buffer is actually C<SvOOK_offset()> bytes before SvPVX.
-This offset used to be stored in SvIVX, but is now stored within the spare
-part of the buffer.
-
- U32 SvOOK(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvOOK_offset
-X<SvOOK_offset>
-
-Reads into I<len> the offset from SvPVX back to the true start of the
-allocated buffer, which will be non-zero if C<sv_chop> has been used to
-efficiently remove characters from start of the buffer. Implemented as a
-macro, which takes the address of I<len>, which must be of type C<STRLEN>.
-Evaluates I<sv> more than once. Sets I<len> to 0 if C<SvOOK(sv)> is false.
-
- void SvOOK_offset(NN SV*sv, STRLEN len)
-
-=for hackers
-Found in file sv.h
-
-=item SvPOK
-X<SvPOK>
-
-Returns a U32 value indicating whether the SV contains a character
-string.
-
- U32 SvPOK(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvPOKp
-X<SvPOKp>
-
-Returns a U32 value indicating whether the SV contains a character string.
-Checks the B<private> setting. Use C<SvPOK> instead.
-
- U32 SvPOKp(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvPOK_off
-X<SvPOK_off>
-
-Unsets the PV status of an SV.
-
- void SvPOK_off(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvPOK_on
-X<SvPOK_on>
-
-Tells an SV that it is a string.
-
- void SvPOK_on(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvPOK_only
-X<SvPOK_only>
-
-Tells an SV that it is a string and disables all other OK bits.
-Will also turn off the UTF-8 status.
-
- void SvPOK_only(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvPOK_only_UTF8
-X<SvPOK_only_UTF8>
-
-Tells an SV that it is a string and disables all other OK bits,
-and leaves the UTF-8 status as it was.
-
- void SvPOK_only_UTF8(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvPV
-X<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. 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 SvPVbyte
-X<SvPVbyte>
-
-Like C<SvPV>, but converts sv to byte representation first if necessary.
-
- char* SvPVbyte(SV* sv, STRLEN len)
-
-=for hackers
-Found in file sv.h
-
-=item SvPVbytex
-X<SvPVbytex>
-
-Like C<SvPV>, but converts sv to byte representation first if necessary.
-Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte>
-otherwise.
-
- char* SvPVbytex(SV* sv, STRLEN len)
-
-=for hackers
-Found in file sv.h
-
-=item SvPVbytex_force
-X<SvPVbytex_force>
-
-Like C<SvPV_force>, but converts sv to byte representation first if necessary.
-Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte_force>
-otherwise.
-
- char* SvPVbytex_force(SV* sv, STRLEN len)
-
-=for hackers
-Found in file sv.h
-
-=item SvPVbyte_force
-X<SvPVbyte_force>
-
-Like C<SvPV_force>, but converts sv to byte representation first if necessary.
-
- char* SvPVbyte_force(SV* sv, STRLEN len)
-
-=for hackers
-Found in file sv.h
-
-=item SvPVbyte_nolen
-X<SvPVbyte_nolen>
-
-Like C<SvPV_nolen>, but converts sv to byte representation first if necessary.
-
- char* SvPVbyte_nolen(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvPVutf8
-X<SvPVutf8>
-
-Like C<SvPV>, but converts sv to utf8 first if necessary.
-
- char* SvPVutf8(SV* sv, STRLEN len)
-
-=for hackers
-Found in file sv.h
-
-=item SvPVutf8x
-X<SvPVutf8x>
-
-Like C<SvPV>, but converts sv to utf8 first if necessary.
-Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8>
-otherwise.
-
- char* SvPVutf8x(SV* sv, STRLEN len)
-
-=for hackers
-Found in file sv.h
-
-=item SvPVutf8x_force
-X<SvPVutf8x_force>
-
-Like C<SvPV_force>, but converts sv to utf8 first if necessary.
-Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8_force>
-otherwise.
-
- char* SvPVutf8x_force(SV* sv, STRLEN len)
-
-=for hackers
-Found in file sv.h
-
-=item SvPVutf8_force
-X<SvPVutf8_force>
-
-Like C<SvPV_force>, but converts sv to utf8 first if necessary.
-
- char* SvPVutf8_force(SV* sv, STRLEN len)
-
-=for hackers
-Found in file sv.h
-
-=item SvPVutf8_nolen
-X<SvPVutf8_nolen>
-
-Like C<SvPV_nolen>, but converts sv to utf8 first if necessary.
-
- char* SvPVutf8_nolen(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvPVX
-X<SvPVX>
-
-Returns a pointer to the physical string in the SV. The SV must contain a
-string.
-
- char* SvPVX(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvPVx
-X<SvPVx>
-
-A version of C<SvPV> which guarantees to evaluate C<sv> only once.
-Only use this if C<sv> is an expression with side effects, otherwise use the
-more efficient C<SvPVX>.
-
- char* SvPVx(SV* sv, STRLEN len)
-
-=for hackers
-Found in file sv.h
-
-=item SvPV_force
-X<SvPV_force>
-
-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)
-
-=for hackers
-Found in file sv.h
-
-=item SvPV_force_nomg
-X<SvPV_force_nomg>
-
-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)
-
-=for hackers
-Found in file sv.h
-
-=item SvPV_nolen
-X<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. 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 SvPV_nomg
-X<SvPV_nomg>
-
-Like C<SvPV> but doesn't process magic.
-
- char* SvPV_nomg(SV* sv, STRLEN len)
-
-=for hackers
-Found in file sv.h
-
-=item SvPV_set
-X<SvPV_set>
-
-Set the value of the PV pointer in sv to val. See C<SvIV_set>.
-
- void SvPV_set(SV* sv, char* val)
-
-=for hackers
-Found in file sv.h
-
-=item SvREFCNT
-X<SvREFCNT>
-
-Returns the value of the object's reference count.
-
- U32 SvREFCNT(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvREFCNT_dec
-X<SvREFCNT_dec>
-
-Decrements the reference count of the given SV.
-
- void SvREFCNT_dec(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvREFCNT_inc
-X<SvREFCNT_inc>
-
-Increments the reference count of the given SV.
-
-All of the following SvREFCNT_inc* macros are optimized versions of
-SvREFCNT_inc, and can be replaced with SvREFCNT_inc.
-
- SV* SvREFCNT_inc(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvREFCNT_inc_NN
-X<SvREFCNT_inc_NN>
-
-Same as SvREFCNT_inc, but can only be used if you know I<sv>
-is not NULL. Since we don't have to check the NULLness, it's faster
-and smaller.
-
- SV* SvREFCNT_inc_NN(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvREFCNT_inc_simple
-X<SvREFCNT_inc_simple>
-
-Same as SvREFCNT_inc, but can only be used with expressions without side
-effects. Since we don't have to store a temporary value, it's faster.
-
- SV* SvREFCNT_inc_simple(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvREFCNT_inc_simple_NN
-X<SvREFCNT_inc_simple_NN>
-
-Same as SvREFCNT_inc_simple, but can only be used if you know I<sv>
-is not NULL. Since we don't have to check the NULLness, it's faster
-and smaller.
-
- SV* SvREFCNT_inc_simple_NN(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvREFCNT_inc_simple_void
-X<SvREFCNT_inc_simple_void>
-
-Same as SvREFCNT_inc_simple, but can only be used if you don't need the
-return value. The macro doesn't need to return a meaningful value.
-
- void SvREFCNT_inc_simple_void(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvREFCNT_inc_simple_void_NN
-X<SvREFCNT_inc_simple_void_NN>
-
-Same as SvREFCNT_inc, but can only be used if you don't need the return
-value, and you know that I<sv> is not NULL. The macro doesn't need
-to return a meaningful value, or check for NULLness, so it's smaller
-and faster.
-
- void SvREFCNT_inc_simple_void_NN(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvREFCNT_inc_void
-X<SvREFCNT_inc_void>
-
-Same as SvREFCNT_inc, but can only be used if you don't need the
-return value. The macro doesn't need to return a meaningful value.
-
- void SvREFCNT_inc_void(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvREFCNT_inc_void_NN
-X<SvREFCNT_inc_void_NN>
-
-Same as SvREFCNT_inc, but can only be used if you don't need the return
-value, and you know that I<sv> is not NULL. The macro doesn't need
-to return a meaningful value, or check for NULLness, so it's smaller
-and faster.
-
- void SvREFCNT_inc_void_NN(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvROK
-X<SvROK>
-
-Tests if the SV is an RV.
-
- U32 SvROK(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvROK_off
-X<SvROK_off>
-
-Unsets the RV status of an SV.
-
- void SvROK_off(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvROK_on
-X<SvROK_on>
-
-Tells an SV that it is an RV.
-
- void SvROK_on(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvRV
-X<SvRV>
-
-Dereferences an RV to return the SV.
-
- SV* SvRV(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvRV_set
-X<SvRV_set>
-
-Set the value of the RV pointer in sv to val. See C<SvIV_set>.
-
- void SvRV_set(SV* sv, SV* val)
-
-=for hackers
-Found in file sv.h
-
-=item SvSTASH
-X<SvSTASH>
-
-Returns the stash of the SV.
-
- HV* SvSTASH(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvSTASH_set
-X<SvSTASH_set>
-
-Set the value of the STASH pointer in sv to val. See C<SvIV_set>.
-
- void SvSTASH_set(SV* sv, HV* val)
-
-=for hackers
-Found in file sv.h
-
-=item SvTAINT
-X<SvTAINT>
-
-Taints an SV if tainting is enabled.
-
- void SvTAINT(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvTAINTED
-X<SvTAINTED>
-
-Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
-not.
-
- bool SvTAINTED(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvTAINTED_off
-X<SvTAINTED_off>
-
-Untaints an SV. Be I<very> careful with this routine, as it short-circuits
-some of Perl's fundamental security features. XS module authors should not
-use this function unless they fully understand all the implications of
-unconditionally untainting the value. Untainting should be done in the
-standard perl fashion, via a carefully crafted regexp, rather than directly
-untainting variables.
-
- void SvTAINTED_off(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvTAINTED_on
-X<SvTAINTED_on>
-
-Marks an SV as tainted if tainting is enabled.
-
- void SvTAINTED_on(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvTRUE
-X<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
-X<SvTYPE>
-
-Returns the type of the SV. See C<svtype>.
-
- svtype SvTYPE(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvUOK
-X<SvUOK>
-
-Returns a boolean indicating whether the SV contains an unsigned integer.
-
- bool SvUOK(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvUPGRADE
-X<SvUPGRADE>
-
-Used to upgrade an SV to a more complex form. Uses C<sv_upgrade> to
-perform the upgrade if necessary. See C<svtype>.
-
- void SvUPGRADE(SV* sv, svtype type)
-
-=for hackers
-Found in file sv.h
-
-=item SvUTF8
-X<SvUTF8>
-
-Returns a U32 value indicating whether the SV contains UTF-8 encoded data.
-Call this after SvPV() in case any call to string overloading updates the
-internal flag.
-
- U32 SvUTF8(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvUTF8_off
-X<SvUTF8_off>
-
-Unsets the UTF-8 status of an SV.
-
- void SvUTF8_off(SV *sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvUTF8_on
-X<SvUTF8_on>
-
-Turn on the UTF-8 status of an SV (the data is not changed, just the flag).
-Do not use frivolously.
-
- void SvUTF8_on(SV *sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvUV
-X<SvUV>
-
-Coerces the given SV to an unsigned integer and returns it. See C<SvUVx>
-for a version which guarantees to evaluate sv only once.
-
- UV SvUV(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvUVX
-X<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
-X<SvUVx>
-
-Coerces the given SV to an unsigned integer and returns it. Guarantees to
-C<sv> only once. Only use this if C<sv> is an expression with side effects,
-otherwise use the more efficient C<SvUV>.
-
- UV SvUVx(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvUV_nomg
-X<SvUV_nomg>
-
-Like C<SvUV> but doesn't process magic.
-
- UV SvUV_nomg(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item SvUV_set
-X<SvUV_set>
-
-Set the value of the UV pointer in sv to val. See C<SvIV_set>.
-
- void SvUV_set(SV* sv, UV val)
-
-=for hackers
-Found in file sv.h
-
-=item SvVOK
-X<SvVOK>
-
-Returns a boolean indicating whether the SV contains a v-string.
-
- bool SvVOK(SV* sv)
-
-=for hackers
-Found in file sv.h
-
-=item sv_catpvn_nomg
-X<sv_catpvn_nomg>
-
-Like C<sv_catpvn> but doesn't process magic.
-
- void sv_catpvn_nomg(SV* sv, const char* ptr, STRLEN len)
-
-=for hackers
-Found in file sv.h
-
-=item sv_catsv_nomg
-X<sv_catsv_nomg>
-
-Like C<sv_catsv> but doesn't process magic.
-
- void sv_catsv_nomg(SV* dsv, SV* ssv)
-
-=for hackers
-Found in file sv.h
-
-=item sv_derived_from
-X<sv_derived_from>
-
-Returns a boolean indicating whether the SV is derived from the specified class
-I<at the C level>. To check derivation at the Perl level, call C<isa()> as a
-normal Perl method.
-
- bool sv_derived_from(SV* sv, const char *const name)
-
-=for hackers
-Found in file universal.c
-
-=item sv_does
-X<sv_does>
-
-Returns a boolean indicating whether the SV performs a specific, named role.
-The SV can be a Perl object or the name of a Perl class.
-
- bool sv_does(SV* sv, const char *const name)
-
-=for hackers
-Found in file universal.c
-
-=item sv_report_used
-X<sv_report_used>
-
-Dump the contents of all SVs not yet freed. (Debugging aid).
-
- void sv_report_used()
-
-=for hackers
-Found in file sv.c
-
-=item sv_setsv_nomg
-X<sv_setsv_nomg>
-
-Like C<sv_setsv> but doesn't process magic.
-
- void sv_setsv_nomg(SV* dsv, SV* ssv)
-
-=for hackers
-Found in file sv.h
-
-=item sv_utf8_upgrade_nomg
-X<sv_utf8_upgrade_nomg>
-
-Like sv_utf8_upgrade, but doesn't do magic on C<sv>
-
- STRLEN sv_utf8_upgrade_nomg(NN SV *sv)
-
-=for hackers
-Found in file sv.h
-
-
-=back
-
-=head1 SV-Body Allocation
-
-=over 8
-
-=item looks_like_number
-X<looks_like_number>
-
-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.
-
- I32 looks_like_number(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item newRV_noinc
-X<newRV_noinc>
-
-Creates an RV wrapper for an SV. The reference count for the original
-SV is B<not> incremented.
-
- SV* newRV_noinc(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item newSV
-X<newSV>
-
-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
-trailing 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.
-
-In 5.9.3, newSV() replaces the older NEWSV() API, and drops the first
-parameter, I<x>, a debug aid which allowed callers to identify themselves.
-This aid has been superseded by a new build option, PERL_MEM_LOG (see
-L<perlhack/PERL_MEM_LOG>). The older API is still there for use in XS
-modules supporting older perls.
-
- SV* newSV(const STRLEN len)
-
-=for hackers
-Found in file sv.c
-
-=item newSVhek
-X<newSVhek>
-
-Creates a new SV from the hash key structure. It will generate scalars that
-point to the shared string table where possible. Returns a new (undefined)
-SV if the hek is NULL.
-
- SV* newSVhek(const HEK *const hek)
-
-=for hackers
-Found in file sv.c
-
-=item newSViv
-X<newSViv>
-
-Creates a new SV and copies an integer into it. The reference count for the
-SV is set to 1.
-
- SV* newSViv(const IV i)
-
-=for hackers
-Found in file sv.c
-
-=item newSVnv
-X<newSVnv>
-
-Creates a new SV and copies a floating point value into it.
-The reference count for the SV is set to 1.
-
- SV* newSVnv(const NV n)
-
-=for hackers
-Found in file sv.c
-
-=item newSVpv
-X<newSVpv>
-
-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 *const s, const STRLEN len)
-
-=for hackers
-Found in file sv.c
-
-=item newSVpvf
-X<newSVpvf>
-
-Creates a new SV and initializes it with the string formatted like
-C<sprintf>.
-
- SV* newSVpvf(const char *const pat, ...)
-
-=for hackers
-Found in file sv.c
-
-=item newSVpvn
-X<newSVpvn>
-
-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. If the C<s> argument is NULL the new SV will be undefined.
-
- SV* newSVpvn(const char *const s, const STRLEN len)
-
-=for hackers
-Found in file sv.c
-
-=item newSVpvn_flags
-X<newSVpvn_flags>
-
-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. If the C<s> argument is NULL the new SV will be undefined.
-Currently the only flag bits accepted are C<SVf_UTF8> and C<SVs_TEMP>.
-If C<SVs_TEMP> is set, then C<sv2mortal()> is called on the result before
-returning. If C<SVf_UTF8> is set, then it will be set on the new SV.
-C<newSVpvn_utf8()> is a convenience wrapper for this function, defined as
-
- #define newSVpvn_utf8(s, len, u) \
- newSVpvn_flags((s), (len), (u) ? SVf_UTF8 : 0)
-
- SV* newSVpvn_flags(const char *const s, const STRLEN len, const U32 flags)
-
-=for hackers
-Found in file sv.c
-
-=item newSVpvn_share
-X<newSVpvn_share>
-
-Creates a new SV with its SvPVX_const 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. If the C<hash> parameter is non-zero, that
-value is used; otherwise the hash is computed. The string's hash can be later
-be retrieved from the SV with the C<SvSHARED_HASH()> macro. The idea here is
-that as the string table is used for shared hash keys these strings will have
-SvPVX_const == HeKEY and hash lookup will avoid string compare.
-
- SV* newSVpvn_share(const char* s, I32 len, U32 hash)
-
-=for hackers
-Found in file sv.c
-
-=item newSVpvs
-X<newSVpvs>
-
-Like C<newSVpvn>, but takes a literal string instead of a string/length pair.
-
- SV* newSVpvs(const char* s)
-
-=for hackers
-Found in file handy.h
-
-=item newSVpvs_flags
-X<newSVpvs_flags>
-
-Like C<newSVpvn_flags>, but takes a literal string instead of a string/length
-pair.
-
- SV* newSVpvs_flags(const char* s, U32 flags)
-
-=for hackers
-Found in file handy.h
-
-=item newSVpvs_share
-X<newSVpvs_share>
-
-Like C<newSVpvn_share>, but takes a literal string instead of a string/length
-pair and omits the hash parameter.
-
- SV* newSVpvs_share(const char* s)
-
-=for hackers
-Found in file handy.h
-
-=item newSVrv
-X<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.
-
- SV* newSVrv(SV *const rv, const char *const classname)
-
-=for hackers
-Found in file sv.c
-
-=item newSVsv
-X<newSVsv>
-
-Creates a new SV which is an exact duplicate of the original SV.
-(Uses C<sv_setsv>).
-
- SV* newSVsv(SV *const old)
-
-=for hackers
-Found in file sv.c
-
-=item newSVuv
-X<newSVuv>
-
-Creates a new SV and copies an unsigned integer into it.
-The reference count for the SV is set to 1.
-
- SV* newSVuv(const UV u)
-
-=for hackers
-Found in file sv.c
-
-=item newSV_type
-X<newSV_type>
-
-Creates a new SV, of the type specified. The reference count for the new SV
-is set to 1.
-
- SV* newSV_type(const svtype type)
-
-=for hackers
-Found in file sv.c
-
-=item sv_2bool
-X<sv_2bool>
-
-This function is only called on magical items, and is only used by
-sv_true() or its macro equivalent.
-
- bool sv_2bool(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_2cv
-X<sv_2cv>
-
-Using various gambits, try to get a CV from an SV; in addition, try if
-possible to set C<*st> and C<*gvp> to the stash and GV associated with it.
-The flags in C<lref> are passed to sv_fetchsv.
-
- CV* sv_2cv(SV* sv, HV **const st, GV **const gvp, const I32 lref)
-
-=for hackers
-Found in file sv.c
-
-=item sv_2io
-X<sv_2io>
-
-Using various gambits, try to get an IO from an SV: the IO slot if its a
-GV; or the recursive result if we're an RV; or the IO slot of the symbol
-named after the PV if we're a string.
-
- IO* sv_2io(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_2iv_flags
-X<sv_2iv_flags>
-
-Return the integer value of an SV, doing any necessary string
-conversion. If flags includes SV_GMAGIC, does an mg_get() first.
-Normally used via the C<SvIV(sv)> and C<SvIVx(sv)> macros.
-
- IV sv_2iv_flags(SV *const sv, const I32 flags)
-
-=for hackers
-Found in file sv.c
-
-=item sv_2mortal
-X<sv_2mortal>
-
-Marks an existing SV as mortal. The SV will be destroyed "soon", either
-by an explicit call to FREETMPS, or by an implicit call at places such as
-statement boundaries. SvTEMP() is turned on which means that the SV's
-string buffer can be "stolen" if this SV is copied. See also C<sv_newmortal>
-and C<sv_mortalcopy>.
-
- SV* sv_2mortal(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_2nv
-X<sv_2nv>
-
-Return the num value of an SV, doing any necessary string or integer
-conversion, magic etc. Normally used via the C<SvNV(sv)> and C<SvNVx(sv)>
-macros.
-
- NV sv_2nv(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_2pvbyte
-X<sv_2pvbyte>
-
-Return a pointer to the byte-encoded representation of the SV, and set *lp
-to its length. May cause the SV to be downgraded from UTF-8 as a
-side-effect.
-
-Usually accessed via the C<SvPVbyte> macro.
-
- char* sv_2pvbyte(SV *const sv, STRLEN *const lp)
-
-=for hackers
-Found in file sv.c
-
-=item sv_2pvutf8
-X<sv_2pvutf8>
-
-Return a pointer to the UTF-8-encoded representation of the SV, and set *lp
-to its length. May cause the SV to be upgraded to UTF-8 as a side-effect.
-
-Usually accessed via the C<SvPVutf8> macro.
-
- char* sv_2pvutf8(SV *const sv, STRLEN *const lp)
-
-=for hackers
-Found in file sv.c
-
-=item sv_2pv_flags
-X<sv_2pv_flags>
-
-Returns a pointer to the string value of an SV, and sets *lp to its length.
-If flags includes SV_GMAGIC, does an mg_get() first. Coerces sv to a string
-if necessary.
-Normally invoked via the C<SvPV_flags> macro. C<sv_2pv()> and C<sv_2pv_nomg>
-usually end up here too.
-
- char* sv_2pv_flags(SV *const sv, STRLEN *const lp, const I32 flags)
-
-=for hackers
-Found in file sv.c
-
-=item sv_2uv_flags
-X<sv_2uv_flags>
-
-Return the unsigned integer value of an SV, doing any necessary string
-conversion. If flags includes SV_GMAGIC, does an mg_get() first.
-Normally used via the C<SvUV(sv)> and C<SvUVx(sv)> macros.
-
- UV sv_2uv_flags(SV *const sv, const I32 flags)
-
-=for hackers
-Found in file sv.c
-
-=item sv_backoff
-X<sv_backoff>
-
-Remove any string offset. You should normally use the C<SvOOK_off> macro
-wrapper instead.
-
- int sv_backoff(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_bless
-X<sv_bless>
-
-Blesses an SV into a specified package. The SV must be an RV. The package
-must be designated by its stash (see C<gv_stashpv()>). The reference count
-of the SV is unaffected.
-
- SV* sv_bless(SV *const sv, HV *const stash)
-
-=for hackers
-Found in file sv.c
-
-=item sv_catpv
-X<sv_catpv>
-
-Concatenates the string onto the end of the string which is in the SV.
-If the SV has the UTF-8 status set, then the bytes appended should be
-valid UTF-8. Handles 'get' magic, but not 'set' magic. See C<sv_catpv_mg>.
-
- void sv_catpv(SV *const sv, const char* ptr)
-
-=for hackers
-Found in file sv.c
-
-=item sv_catpvf
-X<sv_catpvf>
-
-Processes its arguments like C<sprintf> and appends the formatted
-output to an SV. If the appended data contains "wide" characters
-(including, but not limited to, SVs with a UTF-8 PV formatted with %s,
-and characters >255 formatted with %c), the original SV might get
-upgraded to UTF-8. Handles 'get' magic, but not 'set' magic. See
-C<sv_catpvf_mg>. If the original SV was UTF-8, the pattern should be
-valid UTF-8; if the original SV was bytes, the pattern should be too.
-
- void sv_catpvf(SV *const sv, const char *const pat, ...)
-
-=for hackers
-Found in file sv.c
-
-=item sv_catpvf_mg
-X<sv_catpvf_mg>
-
-Like C<sv_catpvf>, but also handles 'set' magic.
-
- void sv_catpvf_mg(SV *const sv, const char *const pat, ...)
-
-=for hackers
-Found in file sv.c
-
-=item sv_catpvn
-X<sv_catpvn>
-
-Concatenates the string onto the end of the string which is in the SV. The
-C<len> indicates number of bytes to copy. If the SV has the UTF-8
-status set, then the bytes appended should be valid UTF-8.
-Handles 'get' magic, but not 'set' magic. See C<sv_catpvn_mg>.
-
- void sv_catpvn(SV *dsv, const char *sstr, STRLEN len)
-
-=for hackers
-Found in file sv.c
-
-=item sv_catpvn_flags
-X<sv_catpvn_flags>
-
-Concatenates the string onto the end of the string which is in the SV. The
-C<len> indicates number of bytes to copy. If the SV has the UTF-8
-status set, then the bytes appended should be valid UTF-8.
-If C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<dsv> if
-appropriate, else not. C<sv_catpvn> and C<sv_catpvn_nomg> are implemented
-in terms of this function.
-
- void sv_catpvn_flags(SV *const dstr, const char *sstr, const STRLEN len, const I32 flags)
-
-=for hackers
-Found in file sv.c
-
-=item sv_catpvs
-X<sv_catpvs>
-
-Like C<sv_catpvn>, but takes a literal string instead of a string/length pair.
-
- void sv_catpvs(SV* sv, const char* s)
-
-=for hackers
-Found in file handy.h
-
-=item sv_catpv_mg
-X<sv_catpv_mg>
-
-Like C<sv_catpv>, but also handles 'set' magic.
-
- void sv_catpv_mg(SV *const sv, const char *const ptr)
-
-=for hackers
-Found in file sv.c
-
-=item sv_catsv
-X<sv_catsv>
-
-Concatenates the string from SV C<ssv> onto the end of the string in
-SV C<dsv>. Modifies C<dsv> but not C<ssv>. Handles 'get' magic, but
-not 'set' magic. See C<sv_catsv_mg>.
-
- void sv_catsv(SV *dstr, SV *sstr)
-
-=for hackers
-Found in file sv.c
-
-=item sv_catsv_flags
-X<sv_catsv_flags>
-
-Concatenates the string from SV C<ssv> onto the end of the string in
-SV C<dsv>. Modifies C<dsv> but not C<ssv>. If C<flags> has C<SV_GMAGIC>
-bit set, will C<mg_get> on the SVs if appropriate, else not. C<sv_catsv>
-and C<sv_catsv_nomg> are implemented in terms of this function.
-
- void sv_catsv_flags(SV *const dsv, SV *const ssv, const I32 flags)
-
-=for hackers
-Found in file sv.c
-
-=item sv_chop
-X<sv_chop>
-
-Efficient removal of characters from the beginning of the string buffer.
-SvPOK(sv) must be true and the C<ptr> must be a pointer to somewhere inside
-the string buffer. The C<ptr> becomes the first character of the adjusted
-string. Uses the "OOK hack".
-Beware: after this function returns, C<ptr> and SvPVX_const(sv) may no longer
-refer to the same chunk of data.
-
- void sv_chop(SV *const sv, const char *const ptr)
-
-=for hackers
-Found in file sv.c
-
-=item sv_clear
-X<sv_clear>
-
-Clear an SV: call any destructors, free up any memory used by the body,
-and free the body itself. The SV's head is I<not> freed, although
-its type is set to all 1's so that it won't inadvertently be assumed
-to be live during global destruction etc.
-This function should only be called when REFCNT is zero. Most of the time
-you'll want to call C<sv_free()> (or its macro wrapper C<SvREFCNT_dec>)
-instead.
-
- void sv_clear(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_cmp
-X<sv_cmp>
-
-Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the
-string in C<sv1> is less than, equal to, or greater than the string in
-C<sv2>. Is UTF-8 and 'use bytes' aware, handles get magic, and will
-coerce its args to strings if necessary. See also C<sv_cmp_locale>.
-
- I32 sv_cmp(SV *const sv1, SV *const sv2)
-
-=for hackers
-Found in file sv.c
-
-=item sv_cmp_locale
-X<sv_cmp_locale>
-
-Compares the strings in two SVs in a locale-aware manner. Is UTF-8 and
-'use bytes' aware, handles get magic, and will coerce its args to strings
-if necessary. See also C<sv_cmp>.
-
- I32 sv_cmp_locale(SV *const sv1, SV *const sv2)
-
-=for hackers
-Found in file sv.c
-
-=item sv_collxfrm
-X<sv_collxfrm>
-
-Add Collate Transform magic to an SV if it doesn't already have it.
-
-Any scalar variable may carry PERL_MAGIC_collxfrm magic that contains the
-scalar data of the variable, but transformed to such a format that a normal
-memory comparison can be used to compare the data according to the locale
-settings.
-
- char* sv_collxfrm(SV *const sv, STRLEN *const nxp)
-
-=for hackers
-Found in file sv.c
-
-=item sv_copypv
-X<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
-UTF8 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 *const dsv, SV *const ssv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_dec
-X<sv_dec>
-
-Auto-decrement of the value in the SV, doing string to numeric conversion
-if necessary. Handles 'get' magic.
-
- void sv_dec(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_eq
-X<sv_eq>
-
-Returns a boolean indicating whether the strings in the two SVs are
-identical. Is UTF-8 and 'use bytes' aware, handles get magic, and will
-coerce its args to strings if necessary.
-
- I32 sv_eq(SV* sv1, SV* sv2)
-
-=for hackers
-Found in file sv.c
-
-=item sv_force_normal_flags
-X<sv_force_normal_flags>
-
-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; 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 addition, 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 *const sv, const U32 flags)
-
-=for hackers
-Found in file sv.c
-
-=item sv_free
-X<sv_free>
-
-Decrement an SV's reference count, and if it drops to zero, call
-C<sv_clear> to invoke destructors and free up any memory used by
-the body; finally, deallocate the SV's head itself.
-Normally called via a wrapper macro C<SvREFCNT_dec>.
-
- void sv_free(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_gets
-X<sv_gets>
-
-Get a line from the filehandle and store it into the SV, optionally
-appending to the currently-stored string.
-
- char* sv_gets(SV *const sv, PerlIO *const fp, I32 append)
-
-=for hackers
-Found in file sv.c
-
-=item sv_grow
-X<sv_grow>
-
-Expands the character buffer in the SV. If necessary, uses C<sv_unref> and
-upgrades the SV to C<SVt_PV>. Returns a pointer to the character buffer.
-Use the C<SvGROW> wrapper instead.
-
- char* sv_grow(SV *const sv, STRLEN newlen)
-
-=for hackers
-Found in file sv.c
-
-=item sv_inc
-X<sv_inc>
-
-Auto-increment of the value in the SV, doing string to numeric conversion
-if necessary. Handles 'get' magic.
-
- void sv_inc(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_insert
-X<sv_insert>
-
-Inserts a string at the specified offset/length within the SV. Similar to
-the Perl substr() function. Handles get magic.
-
- void sv_insert(SV *const bigstr, const STRLEN offset, const STRLEN len, const char *const little, const STRLEN littlelen)
-
-=for hackers
-Found in file sv.c
-
-=item sv_insert_flags
-X<sv_insert_flags>
-
-Same as C<sv_insert>, but the extra C<flags> are passed the C<SvPV_force_flags> that applies to C<bigstr>.
-
- void sv_insert_flags(SV *const bigstr, const STRLEN offset, const STRLEN len, const char *const little, const STRLEN littlelen, const U32 flags)
-
-=for hackers
-Found in file sv.c
-
-=item sv_isa
-X<sv_isa>
-
-Returns a boolean indicating whether the SV is blessed into the specified
-class. This does not check for subtypes; use C<sv_derived_from> to verify
-an inheritance relationship.
-
- int sv_isa(SV* sv, const char *const name)
-
-=for hackers
-Found in file sv.c
-
-=item sv_isobject
-X<sv_isobject>
-
-Returns a boolean indicating whether the SV is an RV pointing to a blessed
-object. If the SV is not an RV, or if the object is not blessed, then this
-will return false.
-
- int sv_isobject(SV* sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_len
-X<sv_len>
-
-Returns the length of the string in the SV. Handles magic and type
-coercion. See also C<SvCUR>, which gives raw access to the xpv_cur slot.
-
- STRLEN sv_len(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_len_utf8
-X<sv_len_utf8>
-
-Returns the number of characters in the string in an SV, counting wide
-UTF-8 bytes as a single character. Handles magic and type coercion.
-
- STRLEN sv_len_utf8(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_magic
-X<sv_magic>
-
-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.
-
-See C<sv_magicext> (which C<sv_magic> now calls) for a description of the
-handling of the C<name> and C<namlen> arguments.
-
-You need to use C<sv_magicext> to add magic to SvREADONLY SVs and also
-to add more than one instance of the same 'how'.
-
- void sv_magic(SV *const sv, SV *const obj, const int how, const char *const name, const I32 namlen)
-
-=for hackers
-Found in file sv.c
-
-=item sv_magicext
-X<sv_magicext>
-
-Adds magic to an SV, upgrading it if necessary. Applies the
-supplied vtable and returns a pointer to the magic added.
-
-Note that C<sv_magicext> will allow things that C<sv_magic> will not.
-In particular, you can add magic to SvREADONLY SVs, and add more than
-one instance of the same 'how'.
-
-If C<namlen> is greater than zero then a C<savepvn> I<copy> of C<name> is
-stored, if C<namlen> is zero then C<name> is stored as-is and - as another
-special case - if C<(name && namlen == HEf_SVKEY)> then C<name> is assumed
-to contain an C<SV*> and is stored as-is with its REFCNT incremented.
-
-(This is now used as a subroutine by C<sv_magic>.)
-
- MAGIC * sv_magicext(SV *const sv, SV *const obj, const int how, const MGVTBL *const vtbl, const char *const name, const I32 namlen)
-
-=for hackers
-Found in file sv.c
-
-=item sv_mortalcopy
-X<sv_mortalcopy>
-
-Creates a new SV which is a copy of the original SV (using C<sv_setsv>).
-The new SV is marked as mortal. It will be destroyed "soon", either by an
-explicit call to FREETMPS, or by an implicit call at places such as
-statement boundaries. See also C<sv_newmortal> and C<sv_2mortal>.
-
- SV* sv_mortalcopy(SV *const oldsv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_newmortal
-X<sv_newmortal>
-
-Creates a new null SV which is mortal. The reference count of the SV is
-set to 1. It will be destroyed "soon", either by an explicit call to
-FREETMPS, or by an implicit call at places such as statement boundaries.
-See also C<sv_mortalcopy> and C<sv_2mortal>.
-
- SV* sv_newmortal()
-
-=for hackers
-Found in file sv.c
-
-=item sv_newref
-X<sv_newref>
-
-Increment an SV's reference count. Use the C<SvREFCNT_inc()> wrapper
-instead.
-
- SV* sv_newref(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_pos_b2u
-X<sv_pos_b2u>
-
-Converts the value pointed to by offsetp from a count of bytes from the
-start of the string, to a count of the equivalent number of UTF-8 chars.
-Handles magic and type coercion.
-
- void sv_pos_b2u(SV *const sv, I32 *const offsetp)
-
-=for hackers
-Found in file sv.c
-
-=item sv_pos_u2b
-X<sv_pos_u2b>
-
-Converts the value pointed to by offsetp from a count of UTF-8 chars from
-the start of the string, to a count of the equivalent number of bytes; if
-lenp is non-zero, it does the same to lenp, but this time starting from
-the offset, rather than from the start of the string. Handles magic and
-type coercion.
-
- void sv_pos_u2b(SV *const sv, I32 *const offsetp, I32 *const lenp)
-
-=for hackers
-Found in file sv.c
-
-=item sv_pvbyten_force
-X<sv_pvbyten_force>
-
-The backend for the C<SvPVbytex_force> macro. Always use the macro instead.
-
- char* sv_pvbyten_force(SV *const sv, STRLEN *const lp)
-
-=for hackers
-Found in file sv.c
-
-=item sv_pvn_force
-X<sv_pvn_force>
-
-Get a sensible string out of the SV somehow.
-A private implementation of the C<SvPV_force> macro for compilers which
-can't cope with complex macro expressions. Always use the macro instead.
-
- char* sv_pvn_force(SV* sv, STRLEN* lp)
-
-=for hackers
-Found in file sv.c
-
-=item sv_pvn_force_flags
-X<sv_pvn_force_flags>
-
-Get a sensible string out of the SV somehow.
-If C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<sv> if
-appropriate, else not. C<sv_pvn_force> and C<sv_pvn_force_nomg> are
-implemented in terms of this function.
-You normally want to use the various wrapper macros instead: see
-C<SvPV_force> and C<SvPV_force_nomg>
-
- char* sv_pvn_force_flags(SV *const sv, STRLEN *const lp, const I32 flags)
-
-=for hackers
-Found in file sv.c
-
-=item sv_pvutf8n_force
-X<sv_pvutf8n_force>
-
-The backend for the C<SvPVutf8x_force> macro. Always use the macro instead.
-
- char* sv_pvutf8n_force(SV *const sv, STRLEN *const lp)
-
-=for hackers
-Found in file sv.c
-
-=item sv_reftype
-X<sv_reftype>
-
-Returns a string describing what the SV is a reference to.
-
- const char* sv_reftype(const SV *const sv, const int ob)
-
-=for hackers
-Found in file sv.c
-
-=item sv_replace
-X<sv_replace>
-
-Make the first argument a copy of the second, then delete the original.
-The target SV physically takes over ownership of the body of the source SV
-and inherits its flags; however, the target keeps any magic it owns,
-and any magic in the source is discarded.
-Note that this is a rather specialist SV copying operation; most of the
-time you'll want to use C<sv_setsv> or one of its many macro front-ends.
-
- void sv_replace(SV *const sv, SV *const nsv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_reset
-X<sv_reset>
-
-Underlying implementation for the C<reset> Perl function.
-Note that the perl-level function is vaguely deprecated.
-
- void sv_reset(const char* s, HV *const stash)
-
-=for hackers
-Found in file sv.c
-
-=item sv_rvweaken
-X<sv_rvweaken>
-
-Weaken a reference: set the C<SvWEAKREF> flag on this RV; give the
-referred-to SV C<PERL_MAGIC_backref> magic if it hasn't already; and
-push a back-reference to this RV onto the array of backreferences
-associated with that magic. If the RV is magical, set magic will be
-called after the RV is cleared.
-
- SV* sv_rvweaken(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setiv
-X<sv_setiv>
-
-Copies an integer into the given SV, upgrading first if necessary.
-Does not handle 'set' magic. See also C<sv_setiv_mg>.
-
- void sv_setiv(SV *const sv, const IV num)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setiv_mg
-X<sv_setiv_mg>
-
-Like C<sv_setiv>, but also handles 'set' magic.
-
- void sv_setiv_mg(SV *const sv, const IV i)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setnv
-X<sv_setnv>
-
-Copies a double into the given SV, upgrading first if necessary.
-Does not handle 'set' magic. See also C<sv_setnv_mg>.
-
- void sv_setnv(SV *const sv, const NV num)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setnv_mg
-X<sv_setnv_mg>
-
-Like C<sv_setnv>, but also handles 'set' magic.
-
- void sv_setnv_mg(SV *const sv, const NV num)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setpv
-X<sv_setpv>
-
-Copies a string into an SV. The string must be null-terminated. Does not
-handle 'set' magic. See C<sv_setpv_mg>.
-
- void sv_setpv(SV *const sv, const char *const ptr)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setpvf
-X<sv_setpvf>
-
-Works like C<sv_catpvf> but copies the text into the SV instead of
-appending it. Does not handle 'set' magic. See C<sv_setpvf_mg>.
-
- void sv_setpvf(SV *const sv, const char *const pat, ...)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setpvf_mg
-X<sv_setpvf_mg>
-
-Like C<sv_setpvf>, but also handles 'set' magic.
-
- void sv_setpvf_mg(SV *const sv, const char *const pat, ...)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setpviv
-X<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 *const sv, const IV num)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setpviv_mg
-X<sv_setpviv_mg>
-
-Like C<sv_setpviv>, but also handles 'set' magic.
-
- void sv_setpviv_mg(SV *const sv, const IV iv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setpvn
-X<sv_setpvn>
-
-Copies a string into an SV. The C<len> parameter indicates the number of
-bytes to be copied. If the C<ptr> argument is NULL the SV will become
-undefined. Does not handle 'set' magic. See C<sv_setpvn_mg>.
-
- void sv_setpvn(SV *const sv, const char *const ptr, const STRLEN len)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setpvn_mg
-X<sv_setpvn_mg>
-
-Like C<sv_setpvn>, but also handles 'set' magic.
-
- void sv_setpvn_mg(SV *const sv, const char *const ptr, const STRLEN len)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setpvs
-X<sv_setpvs>
-
-Like C<sv_setpvn>, but takes a literal string instead of a string/length pair.
-
- void sv_setpvs(SV* sv, const char* s)
-
-=for hackers
-Found in file handy.h
-
-=item sv_setpv_mg
-X<sv_setpv_mg>
-
-Like C<sv_setpv>, but also handles 'set' magic.
-
- void sv_setpv_mg(SV *const sv, const char *const ptr)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setref_iv
-X<sv_setref_iv>
-
-Copies an integer into a new SV, optionally blessing the SV. The C<rv>
-argument will be upgraded to an RV. That RV will be modified to point to
-the new SV. The C<classname> argument indicates the package for the
-blessing. Set C<classname> to C<NULL> to avoid the blessing. The new SV
-will have a reference count of 1, and the RV will be returned.
-
- SV* sv_setref_iv(SV *const rv, const char *const classname, const IV iv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setref_nv
-X<sv_setref_nv>
-
-Copies a double into a new SV, optionally blessing the SV. The C<rv>
-argument will be upgraded to an RV. That RV will be modified to point to
-the new SV. The C<classname> argument indicates the package for the
-blessing. Set C<classname> to C<NULL> to avoid the blessing. The new SV
-will have a reference count of 1, and the RV will be returned.
-
- SV* sv_setref_nv(SV *const rv, const char *const classname, const NV nv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setref_pv
-X<sv_setref_pv>
-
-Copies a pointer into a new SV, optionally blessing the SV. The C<rv>
-argument will be upgraded to an RV. That RV will be modified to point to
-the new SV. If the C<pv> argument is NULL then C<PL_sv_undef> will be placed
-into the SV. The C<classname> argument indicates the package for the
-blessing. Set C<classname> to C<NULL> to avoid the blessing. The new SV
-will have a reference count of 1, and the RV will be returned.
-
-Do not use with other Perl types such as HV, AV, SV, CV, because those
-objects will become corrupted by the pointer copy process.
-
-Note that C<sv_setref_pvn> copies the string while this copies the pointer.
-
- SV* sv_setref_pv(SV *const rv, const char *const classname, void *const pv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setref_pvn
-X<sv_setref_pvn>
-
-Copies a string into a new SV, optionally blessing the SV. The length of the
-string must be specified with C<n>. The C<rv> argument will be upgraded to
-an RV. That RV will be modified to point to the new SV. The C<classname>
-argument indicates the package for the blessing. Set C<classname> to
-C<NULL> to avoid the blessing. The new SV will have a reference count
-of 1, and the RV will be returned.
-
-Note that C<sv_setref_pv> copies the pointer while this copies the string.
-
- SV* sv_setref_pvn(SV *const rv, const char *const classname, const char *const pv, const STRLEN n)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setref_uv
-X<sv_setref_uv>
-
-Copies an unsigned integer into a new SV, optionally blessing the SV. The C<rv>
-argument will be upgraded to an RV. That RV will be modified to point to
-the new SV. The C<classname> argument indicates the package for the
-blessing. Set C<classname> to C<NULL> to avoid the blessing. The new SV
-will have a reference count of 1, and the RV will be returned.
-
- SV* sv_setref_uv(SV *const rv, const char *const classname, const UV uv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setsv
-X<sv_setsv>
-
-Copies the contents of the source SV C<ssv> into the destination SV
-C<dsv>. The source SV may be destroyed if it is mortal, so don't use this
-function if the source SV needs to be reused. Does not handle 'set' magic.
-Loosely speaking, it performs a copy-by-value, obliterating any previous
-content of the destination.
-
-You probably want to use one of the assortment of wrappers, such as
-C<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and
-C<SvSetMagicSV_nosteal>.
-
- void sv_setsv(SV *dstr, SV *sstr)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setsv_flags
-X<sv_setsv_flags>
-
-Copies the contents of the source SV C<ssv> into the destination SV
-C<dsv>. The source SV may be destroyed if it is mortal, so don't use this
-function if the source SV needs to be reused. Does not handle 'set' magic.
-Loosely speaking, it performs a copy-by-value, obliterating any previous
-content of the destination.
-If the C<flags> parameter has the C<SV_GMAGIC> bit set, will C<mg_get> on
-C<ssv> if appropriate, else not. If the C<flags> parameter has the
-C<NOSTEAL> bit set then the buffers of temps will not be stolen. <sv_setsv>
-and C<sv_setsv_nomg> are implemented in terms of this function.
-
-You probably want to use one of the assortment of wrappers, such as
-C<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and
-C<SvSetMagicSV_nosteal>.
-
-This is the primary function for copying scalars, and most other
-copy-ish functions and macros use this underneath.
-
- void sv_setsv_flags(SV *dstr, SV *sstr, const I32 flags)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setsv_mg
-X<sv_setsv_mg>
-
-Like C<sv_setsv>, but also handles 'set' magic.
-
- void sv_setsv_mg(SV *const dstr, SV *const sstr)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setuv
-X<sv_setuv>
-
-Copies an unsigned integer into the given SV, upgrading first if necessary.
-Does not handle 'set' magic. See also C<sv_setuv_mg>.
-
- void sv_setuv(SV *const sv, const UV num)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setuv_mg
-X<sv_setuv_mg>
-
-Like C<sv_setuv>, but also handles 'set' magic.
-
- void sv_setuv_mg(SV *const sv, const UV u)
-
-=for hackers
-Found in file sv.c
-
-=item sv_tainted
-X<sv_tainted>
-
-Test an SV for taintedness. Use C<SvTAINTED> instead.
- bool sv_tainted(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_true
-X<sv_true>
-
-Returns true if the SV has a true value by Perl's rules.
-Use the C<SvTRUE> macro instead, which may call C<sv_true()> or may
-instead use an in-line version.
-
- I32 sv_true(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_unmagic
-X<sv_unmagic>
-
-Removes all magic of type C<type> from an SV.
-
- int sv_unmagic(SV *const sv, const int type)
-
-=for hackers
-Found in file sv.c
-
-=item sv_unref_flags
-X<sv_unref_flags>
-
-Unsets the RV status of the SV, and decrements the reference count of
-whatever was being referenced by the RV. This can almost be thought of
-as a reversal of C<newSVrv>. The C<cflags> argument can contain
-C<SV_IMMEDIATE_UNREF> to force the reference count to be decremented
-(otherwise the decrementing is conditional on the reference count being
-different from one or the reference being a readonly SV).
-See C<SvROK_off>.
-
- void sv_unref_flags(SV *const ref, const U32 flags)
-
-=for hackers
-Found in file sv.c
-
-=item sv_untaint
-X<sv_untaint>
-
-Untaint an SV. Use C<SvTAINTED_off> instead.
- void sv_untaint(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_upgrade
-X<sv_upgrade>
-
-Upgrade an SV to a more complex form. Generally adds a new body type to the
-SV, then copies across as much information as possible from the old body.
-You generally want to use the C<SvUPGRADE> macro wrapper. See also C<svtype>.
-
- void sv_upgrade(SV *const sv, svtype new_type)
-
-=for hackers
-Found in file sv.c
-
-=item sv_usepvn_flags
-X<sv_usepvn_flags>
-
-Tells an SV to use C<ptr> to find its string value. Normally the
-string is stored inside the SV but sv_usepvn allows the SV to use an
-outside string. The C<ptr> should point to memory that was allocated
-by C<malloc>. The string length, C<len>, must be supplied. By default
-this function will realloc (i.e. move) the memory pointed to by C<ptr>,
-so that pointer should not be freed or used by the programmer after
-giving it to sv_usepvn, and neither should any pointers from "behind"
-that pointer (e.g. ptr + 1) be used.
-
-If C<flags> & SV_SMAGIC is true, will call SvSETMAGIC. If C<flags> &
-SV_HAS_TRAILING_NUL is true, then C<ptr[len]> must be NUL, and the realloc
-will be skipped. (i.e. the buffer is actually at least 1 byte longer than
-C<len>, and already meets the requirements for storing in C<SvPVX>)
-
- void sv_usepvn_flags(SV *const sv, char* ptr, const STRLEN len, const U32 flags)
-
-=for hackers
-Found in file sv.c
-
-=item sv_utf8_decode
-X<sv_utf8_decode>
-
-If the PV of the SV is an octet sequence in UTF-8
-and contains a multiple-byte character, the C<SvUTF8> flag is turned on
-so that it looks like a character. If the PV contains only single-byte
-characters, the C<SvUTF8> flag stays being off.
-Scans PV for validity and returns false if the PV is invalid UTF-8.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- bool sv_utf8_decode(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_utf8_downgrade
-X<sv_utf8_downgrade>
-
-Attempts to convert the PV of an SV from characters to bytes.
-If the PV contains a character that cannot fit
-in a byte, this conversion will fail;
-in this 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.
-
- bool sv_utf8_downgrade(SV *const sv, const bool fail_ok)
-
-=for hackers
-Found in file sv.c
-
-=item sv_utf8_encode
-X<sv_utf8_encode>
-
-Converts the PV of an SV to UTF-8, but then turns the C<SvUTF8>
-flag off so that it looks like octets again.
-
- void sv_utf8_encode(SV *const sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_utf8_upgrade
-X<sv_utf8_upgrade>
-
-Converts the PV of an SV to its UTF-8-encoded form.
-Forces the SV to string form if it is not already.
-Will C<mg_get> on C<sv> if appropriate.
-Always sets the SvUTF8 flag to avoid future validity checks even
-if the whole string is the same in UTF-8 as not.
-Returns the number of bytes in the converted string
-
-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
-Found in file sv.c
-
-=item sv_utf8_upgrade_flags
-X<sv_utf8_upgrade_flags>
-
-Converts the PV of an SV to its UTF-8-encoded form.
-Forces the SV to string form if it is not already.
-Always sets the SvUTF8 flag to avoid future validity checks even
-if all the bytes are invariant in UTF-8. If C<flags> has C<SV_GMAGIC> bit set,
-will C<mg_get> on C<sv> if appropriate, else not.
-Returns the number of bytes in the converted string
-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 *const sv, const I32 flags)
-
-=for hackers
-Found in file sv.c
-
-=item sv_utf8_upgrade_nomg
-X<sv_utf8_upgrade_nomg>
-
-Like sv_utf8_upgrade, but doesn't do magic on C<sv>
-
- STRLEN sv_utf8_upgrade_nomg(SV *sv)
-
-=for hackers
-Found in file sv.c
-
-=item sv_vcatpvf
-X<sv_vcatpvf>
-
-Processes its arguments like C<vsprintf> and appends the formatted output
-to an SV. Does not handle 'set' magic. See C<sv_vcatpvf_mg>.
-
-Usually used via its frontend C<sv_catpvf>.
-
- void sv_vcatpvf(SV *const sv, const char *const pat, va_list *const args)
-
-=for hackers
-Found in file sv.c
-
-=item sv_vcatpvfn
-X<sv_vcatpvfn>
-
-Processes its arguments like C<vsprintf> and appends the formatted output
-to an SV. Uses an array of SVs if the C style variable argument list is
-missing (NULL). When running with taint checks enabled, indicates via
-C<maybe_tainted> if results are untrustworthy (often due to the use of
-locales).
-
-Usually used via one of its frontends C<sv_vcatpvf> and C<sv_vcatpvf_mg>.
-
- void sv_vcatpvfn(SV *const sv, const char *const pat, const STRLEN patlen, va_list *const args, SV **const svargs, const I32 svmax, bool *const maybe_tainted)
-
-=for hackers
-Found in file sv.c
-
-=item sv_vcatpvf_mg
-X<sv_vcatpvf_mg>
-
-Like C<sv_vcatpvf>, but also handles 'set' magic.
-
-Usually used via its frontend C<sv_catpvf_mg>.
-
- void sv_vcatpvf_mg(SV *const sv, const char *const pat, va_list *const args)
-
-=for hackers
-Found in file sv.c
-
-=item sv_vsetpvf
-X<sv_vsetpvf>
-
-Works like C<sv_vcatpvf> but copies the text into the SV instead of
-appending it. Does not handle 'set' magic. See C<sv_vsetpvf_mg>.
-
-Usually used via its frontend C<sv_setpvf>.
-
- void sv_vsetpvf(SV *const sv, const char *const pat, va_list *const args)
-
-=for hackers
-Found in file sv.c
-
-=item sv_vsetpvfn
-X<sv_vsetpvfn>
-
-Works like C<sv_vcatpvfn> but copies the text into the SV instead of
-appending it.
-
-Usually used via one of its frontends C<sv_vsetpvf> and C<sv_vsetpvf_mg>.
-
- void sv_vsetpvfn(SV *const sv, const char *const pat, const STRLEN patlen, va_list *const args, SV **const svargs, const I32 svmax, bool *const maybe_tainted)
-
-=for hackers
-Found in file sv.c
-
-=item sv_vsetpvf_mg
-X<sv_vsetpvf_mg>
-
-Like C<sv_vsetpvf>, but also handles 'set' magic.
-
-Usually used via its frontend C<sv_setpvf_mg>.
-
- void sv_vsetpvf_mg(SV *const sv, const char *const pat, va_list *const args)
-
-=for hackers
-Found in file sv.c
-
-
-=back
-
-=head1 Unicode Support
-
-=over 8
-
-=item bytes_from_utf8
-X<bytes_from_utf8>
-
-Converts a string C<s> of length C<len> from UTF-8 into native byte encoding.
-Unlike C<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 consisted entirely of characters that are invariant
-in utf8 (i.e., US-ASCII on non-EBCDIC machines).
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- U8* bytes_from_utf8(const U8 *s, STRLEN *len, bool *is_utf8)
-
-=for hackers
-Found in file utf8.c
-
-=item bytes_to_utf8
-X<bytes_to_utf8>
-
-Converts a string C<s> of length C<len> from the native encoding into UTF-8.
-Returns a pointer to the newly-created string, and sets C<len> to
-reflect the new length.
-
-A NUL character will be written after the end of the string.
-
-If you want to convert to UTF-8 from encodings other than
-the native (Latin1 or EBCDIC),
-see sv_recode_to_utf8().
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- U8* bytes_to_utf8(const U8 *s, STRLEN *len)
-
-=for hackers
-Found in file utf8.c
-
-=item ibcmp_utf8
-X<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
-circumstances. 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 *s1, char **pe1, UV l1, bool u1, const char *s2, char **pe2, UV l2, bool u2)
-
-=for hackers
-Found in file utf8.c
-
-=item is_utf8_char
-X<is_utf8_char>
-
-Tests if some arbitrary number of bytes begins in a valid UTF-8
-character. Note that an INVARIANT (i.e. ASCII on non-EBCDIC machines)
-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(const U8 *s)
-
-=for hackers
-Found in file utf8.c
-
-=item is_utf8_string
-X<is_utf8_string>
-
-Returns true if first C<len> bytes of the given string form a valid
-UTF-8 string, false otherwise. Note that 'a valid UTF-8 string' does
-not mean 'a string that contains code points above 0x7F encoded in UTF-8'
-because a valid ASCII string is a valid UTF-8 string.
-
-See also is_utf8_string_loclen() and is_utf8_string_loc().
-
- bool is_utf8_string(const U8 *s, STRLEN len)
-
-=for hackers
-Found in file utf8.c
-
-=item is_utf8_string_loc
-X<is_utf8_string_loc>
-
-Like is_utf8_string() but stores the location of the failure (in the
-case of "utf8ness failure") or the location s+len (in the case of
-"utf8ness success") in the C<ep>.
-
-See also is_utf8_string_loclen() and is_utf8_string().
-
- bool is_utf8_string_loc(const U8 *s, STRLEN len, const U8 **p)
-
-=for hackers
-Found in file utf8.c
-
-=item is_utf8_string_loclen
-X<is_utf8_string_loclen>
-
-Like is_utf8_string() but stores the location of the failure (in the
-case of "utf8ness failure") or the location s+len (in the case of
-"utf8ness success") in the C<ep>, and the number of UTF-8
-encoded characters in the C<el>.
-
-See also is_utf8_string_loc() and is_utf8_string().
-
- bool is_utf8_string_loclen(const U8 *s, STRLEN len, const U8 **ep, STRLEN *el)
-
-=for hackers
-Found in file utf8.c
-
-=item pv_uni_display
-X<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, const U8 *spv, STRLEN len, STRLEN pvlim, UV flags)
-
-=for hackers
-Found in file utf8.c
-
-=item sv_cat_decode
-X<sv_cat_decode>
-
-The encoding is assumed to be an Encode object, the PV of the ssv is
-assumed to be octets in that encoding and decoding the input starts
-from the position which (PV + *offset) pointed to. The dsv will be
-concatenated the decoded UTF-8 string from ssv. Decoding will terminate
-when the string tstr appears in decoding output or the input ends on
-the PV of the ssv. The value which the offset points will be modified
-to the last input position on the ssv.
-
-Returns TRUE if the terminator was found, else returns FALSE.
-
- bool sv_cat_decode(SV* dsv, SV *encoding, SV *ssv, int *offset, char* tstr, int tlen)
-
-=for hackers
-Found in file sv.c
-
-=item sv_recode_to_utf8
-X<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
-X<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
-X<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.
-
-Both the special and normal mappings are stored lib/unicore/To/Foo.pl,
-and loaded by SWASHNEW, using lib/utf8_heavy.pl. The special (usually,
-but not always, a multicharacter mapping), is tried first.
-
-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().
-
-The "normal" is a string like "ToLower" which means the swash
-%utf8::ToLower.
-
- UV to_utf8_case(const U8 *p, U8* ustrp, STRLEN *lenp, SV **swashp, const char *normal, const char *special)
-
-=for hackers
-Found in file utf8.c
-
-=item to_utf8_fold
-X<to_utf8_fold>
-
-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_MAXBYTES_CASE+1 bytes since the
-foldcase version may be longer than the original character (up to
-three characters).
-
-The first character of the foldcased version is returned
-(but note, as explained above, that there may be more.)
-
- UV to_utf8_fold(const U8 *p, U8* ustrp, STRLEN *lenp)
-
-=for hackers
-Found in file utf8.c
-
-=item to_utf8_lower
-X<to_utf8_lower>
-
-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_MAXBYTES_CASE+1 bytes since the
-lowercase version may be longer than the original character.
-
-The first character of the lowercased version is returned
-(but note, as explained above, that there may be more.)
-
- UV to_utf8_lower(const U8 *p, U8* ustrp, STRLEN *lenp)
-
-=for hackers
-Found in file utf8.c
-
-=item to_utf8_title
-X<to_utf8_title>
-
-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_MAXBYTES_CASE+1 bytes since the
-titlecase version may be longer than the original character.
-
-The first character of the titlecased version is returned
-(but note, as explained above, that there may be more.)
-
- UV to_utf8_title(const U8 *p, U8* ustrp, STRLEN *lenp)
-
-=for hackers
-Found in file utf8.c
-
-=item to_utf8_upper
-X<to_utf8_upper>
-
-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_MAXBYTES_CASE+1 bytes since
-the uppercase version may be longer than the original character.
-
-The first character of the uppercased version is returned
-(but note, as explained above, that there may be more.)
-
- UV to_utf8_upper(const U8 *p, U8* ustrp, STRLEN *lenp)
-
-=for hackers
-Found in file utf8.c
-
-=item utf8n_to_uvchr
-X<utf8n_to_uvchr>
-
-flags
-
-Returns the native character value of the first character in the string
-C<s>
-which is assumed to be in UTF-8 encoding; C<retlen> will be set to the
-length, in bytes, of that character.
-
-Allows length and flags to be passed to low level routine.
-
- UV utf8n_to_uvchr(const U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags)
-
-=for hackers
-Found in file utf8.c
-
-=item utf8n_to_uvuni
-X<utf8n_to_uvuni>
-
-Bottom level UTF-8 decode routine.
-Returns the Unicode code point value of the first character in the string C<s>
-which is assumed to be in UTF-8 encoding and no longer than C<curlen>;
-C<retlen> will be set to the length, in bytes, of that character.
-
-If C<s> does not point to a well-formed UTF-8 character, the behaviour
-is dependent on the value of C<flags>: if it contains UTF8_CHECK_ONLY,
-it is assumed that the caller will raise a warning, and this function
-will silently just set C<retlen> to C<-1> and return zero. If the
-C<flags> does not contain UTF8_CHECK_ONLY, warnings about
-malformations will be given, C<retlen> will be set to the expected
-length of the UTF-8 character in bytes, and zero will be returned.
-
-The C<flags> can also contain various flags to allow deviations from
-the strict UTF-8 encoding (see F<utf8.h>).
-
-Most code should use utf8_to_uvchr() rather than call this directly.
-
- UV utf8n_to_uvuni(const U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags)
-
-=for hackers
-Found in file utf8.c
-
-=item utf8_distance
-X<utf8_distance>
-
-Returns the number of UTF-8 characters between the UTF-8 pointers C<a>
-and C<b>.
-
-WARNING: use only if you *know* that the pointers point inside the
-same UTF-8 buffer.
-
- IV utf8_distance(const U8 *a, const U8 *b)
-
-=for hackers
-Found in file utf8.c
-
-=item utf8_hop
-X<utf8_hop>
-
-Return the UTF-8 pointer C<s> displaced by C<off> characters, either
-forward or backward.
-
-WARNING: do not use the following unless you *know* C<off> is within
-the UTF-8 data pointed to by C<s> *and* that on entry C<s> is aligned
-on the first byte of character or just after the last byte of a character.
-
- U8* utf8_hop(const U8 *s, I32 off)
-
-=for hackers
-Found in file utf8.c
-
-=item utf8_length
-X<utf8_length>
-
-Return the length of the UTF-8 char encoded string C<s> in characters.
-Stops at C<e> (inclusive). If C<e E<lt> s> or if the scan would end
-up past C<e>, croaks.
-
- STRLEN utf8_length(const U8* s, const U8 *e)
-
-=for hackers
-Found in file utf8.c
-
-=item utf8_to_bytes
-X<utf8_to_bytes>
-
-Converts a string C<s> of length C<len> from UTF-8 into native byte encoding.
-Unlike C<bytes_to_utf8>, this over-writes the original string, and
-updates len to contain the new length.
-Returns zero on failure, setting C<len> to -1.
-
-If you need a copy of the string, see C<bytes_from_utf8>.
-
-NOTE: this function is experimental and may change or be
-removed without notice.
-
- U8* utf8_to_bytes(U8 *s, STRLEN *len)
-
-=for hackers
-Found in file utf8.c
-
-=item utf8_to_uvchr
-X<utf8_to_uvchr>
-
-Returns the native character value of the first character in the string C<s>
-which is assumed to be in UTF-8 encoding; C<retlen> will be set to the
-length, in bytes, of that character.
-
-If C<s> does not point to a well-formed UTF-8 character, zero is
-returned and retlen is set, if possible, to -1.
-
- UV utf8_to_uvchr(const U8 *s, STRLEN *retlen)
-
-=for hackers
-Found in file utf8.c
-
-=item utf8_to_uvuni
-X<utf8_to_uvuni>
-
-Returns the Unicode code point of the first character in the string C<s>
-which is assumed to be in UTF-8 encoding; C<retlen> will be set to the
-length, in bytes, of that character.
-
-This function should only be used when the returned UV is considered
-an index into the Unicode semantic tables (e.g. swashes).
-
-If C<s> does not point to a well-formed UTF-8 character, zero is
-returned and retlen is set, if possible, to -1.
-
- UV utf8_to_uvuni(const U8 *s, STRLEN *retlen)
-
-=for hackers
-Found in file utf8.c
-
-=item uvchr_to_utf8
-X<uvchr_to_utf8>
-
-Adds the UTF-8 representation of the Native codepoint C<uv> to the end
-of the string C<d>; C<d> should be have at least C<UTF8_MAXBYTES+1> free
-bytes available. The return value is the pointer to the byte after the
-end of the new character. In other words,
-
- d = uvchr_to_utf8(d, uv);
-
-is the recommended wide native character-aware way of saying
-
- *(d++) = uv;
-
- U8* uvchr_to_utf8(U8 *d, UV uv)
-
-=for hackers
-Found in file utf8.c
-
-=item uvuni_to_utf8_flags
-X<uvuni_to_utf8_flags>
-
-Adds the UTF-8 representation of the Unicode codepoint C<uv> to the end
-of the string C<d>; C<d> should be have at least C<UTF8_MAXBYTES+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_flags(d, uv, flags);
-
-or, in most cases,
-
- d = uvuni_to_utf8(d, uv);
-
-(which is equivalent to)
-
- d = uvuni_to_utf8_flags(d, uv, 0);
-
-is the recommended Unicode-aware way of saying
-
- *(d++) = uv;
-
- U8* uvuni_to_utf8_flags(U8 *d, UV uv, UV flags)
-
-=for hackers
-Found in file utf8.c
-
-
-=back
-
-=head1 Variables created by C<xsubpp> and C<xsubpp> internal functions
-
-=over 8
-
-=item ax
-X<ax>
-
-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.
-
- I32 ax
-
-=for hackers
-Found in file XSUB.h
-
-=item CLASS
-X<CLASS>
-
-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>.
-
- char* CLASS
-
-=for hackers
-Found in file XSUB.h
-
-=item dAX
-X<dAX>
-
-Sets up the C<ax> variable.
-This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
-
- dAX;
-
-=for hackers
-Found in file XSUB.h
-
-=item dAXMARK
-X<dAXMARK>
-
-Sets up the C<ax> variable and stack marker variable C<mark>.
-This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
-
- dAXMARK;
-
-=for hackers
-Found in file XSUB.h
-
-=item dITEMS
-X<dITEMS>
-
-Sets up the C<items> variable.
-This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
-
- dITEMS;
-
-=for hackers
-Found in file XSUB.h
-
-=item dUNDERBAR
-X<dUNDERBAR>
-
-Sets up the C<padoff_du> variable for an XSUB that wishes to use
-C<UNDERBAR>.
-
- dUNDERBAR;
-
-=for hackers
-Found in file XSUB.h
-
-=item dXSARGS
-X<dXSARGS>
-
-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>.
-
- dXSARGS;
-
-=for hackers
-Found in file XSUB.h
-
-=item dXSI32
-X<dXSI32>
-
-Sets up the C<ix> variable for an XSUB which has aliases. This is usually
-handled automatically by C<xsubpp>.
-
- dXSI32;
-
-=for hackers
-Found in file XSUB.h
-
-=item items
-X<items>
-
-Variable which is setup by C<xsubpp> to indicate the number of
-items on the stack. See L<perlxs/"Variable-length Parameter Lists">.
-
- I32 items
-
-=for hackers
-Found in file XSUB.h
-
-=item ix
-X<ix>
-
-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">.
-
- I32 ix
-
-=for hackers
-Found in file XSUB.h
-
-=item newXSproto
-X<newXSproto>
-
-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 RETVAL
-X<RETVAL>
-
-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">.
-
- (whatever) RETVAL
-
-=for hackers
-Found in file XSUB.h
-
-=item ST
-X<ST>
-
-Used to access elements on the XSUB's stack.
-
- SV* ST(int ix)
-
-=for hackers
-Found in file XSUB.h
-
-=item THIS
-X<THIS>
-
-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++">.
-
- (whatever) THIS
-
-=for hackers
-Found in file XSUB.h
-
-=item UNDERBAR
-X<UNDERBAR>
-
-The SV* corresponding to the $_ variable. Works even if there
-is a lexical $_ in scope.
-
-=for hackers
-Found in file XSUB.h
-
-=item XS
-X<XS>
-
-Macro to declare an XSUB and its C parameter list. This is handled by
-C<xsubpp>.
-
-=for hackers
-Found in file XSUB.h
-
-=item XS_VERSION
-X<XS_VERSION>
-
-The version identifier for an XS module. This is usually
-handled automatically by C<ExtUtils::MakeMaker>. See C<XS_VERSION_BOOTCHECK>.
-
-=for hackers
-Found in file XSUB.h
-
-=item XS_VERSION_BOOTCHECK
-X<XS_VERSION_BOOTCHECK>
-
-Macro to verify that a PM module's $VERSION variable matches the XS
-module's C<XS_VERSION> variable. This is usually handled automatically by
-C<xsubpp>. See L<perlxs/"The VERSIONCHECK: Keyword">.
-
- XS_VERSION_BOOTCHECK;
-
-=for hackers
-Found in file XSUB.h
-
-
-=back
-
-=head1 Warning and Dieing
-
-=over 8
-
-=item croak
-X<croak>
-
-This is the XSUB-writer's interface to Perl's C<die> function.
-Normally call this function the same way you call the C C<printf>
-function. Calling C<croak> returns control directly to Perl,
-sidestepping the normal C order of execution. See C<warn>.
-
-If you want to throw an exception object, assign the object to
-C<$@> and then pass C<NULL> to croak():
-
- errsv = get_sv("@", GV_ADD);
- sv_setsv(errsv, exception_object);
- croak(NULL);
-
- void croak(const char* pat, ...)
-
-=for hackers
-Found in file util.c
-
-=item warn
-X<warn>
-
-This is the XSUB-writer's interface to Perl's C<warn> function. Call this
-function the same way you call the C C<printf> function. See C<croak>.
-
- void warn(const char* pat, ...)
-
-=for hackers
-Found in file util.c
-
-
-=back
-
-=head1 AUTHORS
-
-Until May 1997, this document was maintained by Jeff Okamoto
-<okamoto@corp.hp.com>. It is now maintained as part of Perl itself.
-
-With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
-Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
-Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
-Stephen McCamant, and Gurusamy Sarathy.
-
-API Listing originally by Dean Roehrich <roehrich@cray.com>.
-
-Updated to be autogenerated from comments in the source by Benjamin Stuhl.
-
-=head1 SEE ALSO
-
-perlguts(1), perlxs(1), perlxstut(1), perlintern(1)
-
-=cut
-
- ex: set ro:
projects / p5sagit/p5-mst-13.2.git / commitdiff