Miscellaneous Functions
Analyses the string in order to make fast searches on it using fbm_instr() -- the Boyer-Moore algorithm.
Returns the location of the SV in the string delimited by str and strend. It returns NULL if the string can't be found. The sv does not have to be fbm_compiled, but the search will not be as fast then.
Memory Management
Perl's version of strdup(). Returns a pointer to a newly allocated string which is a duplicate of pv. The size of the string is determined by strlen(). The memory allocated for the new string can be freed with the Safefree() function.
Perl's version of what strndup() would be if it existed. Returns a pointer to a newly allocated string which is a duplicate of the first len bytes from pv, plus a trailing NUL byte. The memory allocated for the new string can be freed with the Safefree() function.
A version of savepv() which allocates the duplicate string in memory which is shared between threads.
A version of savepvn() which allocates the duplicate string in memory which is shared between threads. (With the specific difference that a NULL pointer is not acceptable)
A version of savepv()/savepvn() which gets the string to duplicate from the passed in SV using SvPV()
Miscellaneous Functions =for apidoc 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).
Warning and Dieing
This is the XSUB-writer's interface to Perl's die function. Normally call this function the same way you call the C printf function. Calling croak returns control directly to Perl, sidestepping the normal C order of execution. See warn.
If you want to throw an exception object, assign the object to $@ and then pass NULL to croak():
errsv = get_sv("@", GV_ADD);
sv_setsv(errsv, exception_object);
croak(NULL);This is the XSUB-writer's interface to Perl's warn function. Call this function the same way you call the C printf function. See croak.
Miscellaneous Functions
Fill the sv with current working directory
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.
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.
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.
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):
The SV contains a [reference to a] hash
The hash contains a "version" key
The "version" key has [a reference to] an AV as its value
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.
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.
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
Version object aware cmp. Both operands must already have been converted into version objects.
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.
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.
The C library 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 sprintf.
The C library snprintf functionality, if available and standards-compliant (uses vsnprintf, actually). However, if the vsnprintf is not available, will unfortunately use the unsafe vsprintf which can overrun the buffer (there is an overrun check, but that may be too late). Consider using sv_vcatpvf instead, or getting vsnprintf.
The C library vsnprintf if available and standards-compliant. However, if if the vsnprintf is not available, will unfortunately use the unsafe vsprintf which can overrun the buffer (there is an overrun check, but that may be too late). Consider using sv_vcatpvf instead, or getting vsnprintf.