=for apidoc Am|void *|FILE_ptr|FILE * f
=for apidoc Am|Size_t|FILE_cnt|FILE * f
=for apidoc Am|void *|FILE_base|FILE * f
-=for apidoc Am|Size_t|FILE_bufsiz
+=for apidoc Am|Size_t|FILE_bufsiz|FILE *f
=for apidoc_section String Handling
-=for apidoc Am|token|CAT2|token x|token y
-=for apidoc Am|string|STRINGIFY|token x
+=for apidoc Amu|token|CAT2|token x|token y
+=for apidoc Amu|string|STRINGIFY|token x
=for apidoc_section Numeric Functions
-=for apidoc Am|double|Drand01|double x
+=for apidoc Am|double|Drand01
=for apidoc Am|void|seedDrand01|Rand_seed_t x
=for apidoc Am|char *|Gconvert|double x|Size_t n|bool t|char * b
#define TRUE (1)
#define FALSE (0)
-/* The MUTABLE_*() macros cast pointers to the types shown, in such a way
- * (compiler permitting) that casting away const-ness will give a warning;
- * e.g.:
- *
- * const SV *sv = ...;
- * AV *av1 = (AV*)sv; <== BAD: the const has been silently cast away
- * AV *av2 = MUTABLE_AV(sv); <== GOOD: it may warn
+/*
+=for apidoc_section SV Handling
+=for apidoc Am|void *|MUTABLE_PTR|void * p
+=for apidoc_item |AV *|MUTABLE_AV|AV * p
+=for apidoc_item |CV *|MUTABLE_CV|CV * p
+=for apidoc_item |GV *|MUTABLE_GV|GV * p
+=for apidoc_item |HV *|MUTABLE_HV|HV * p
+=for apidoc_item |IO *|MUTABLE_IO|IO * p
+=for apidoc_item |SV *|MUTABLE_SV|SV * p
+
+The C<MUTABLE_I<*>>() macros cast pointers to the types shown, in such a way
+(compiler permitting) that casting away const-ness will give a warning;
+e.g.:
+
+ const SV *sv = ...;
+ AV *av1 = (AV*)sv; <== BAD: the const has been silently
+ cast away
+ AV *av2 = MUTABLE_AV(sv); <== GOOD: it may warn
+
+C<MUTABLE_PTR> is the base macro used to derive new casts. The other
+already-built-in ones return pointers to what their names indicate.
+
+=cut
*/
-#if defined(__GNUC__) && !defined(PERL_GCC_BRACE_GROUPS_FORBIDDEN)
+#if defined(PERL_USE_GCC_BRACE_GROUPS)
# define MUTABLE_PTR(p) ({ void *p_ = (p); p_; })
#else
# define MUTABLE_PTR(p) ((void *) (p))
/*
=for apidoc_section Compiler directives
-=for apidoc Am|void|__ASSERT_|bool expr
+=for apidoc Am||__ASSERT_|bool expr
This is a helper macro to avoid preprocessor issues, replaced by nothing
unless under DEBUGGING, where it expands to an assert of its argument,
#define savesharedpvs(str) Perl_savesharedpvn(aTHX_ STR_WITH_LEN(str))
#define gv_stashpvs(str, create) \
Perl_gv_stashpvn(aTHX_ STR_WITH_LEN(str), create)
-#define gv_fetchpvs(namebeg, add, sv_type) \
- Perl_gv_fetchpvn_flags(aTHX_ STR_WITH_LEN(namebeg), add, sv_type)
-#define gv_fetchpvn(namebeg, len, add, sv_type) \
- Perl_gv_fetchpvn_flags(aTHX_ namebeg, len, add, sv_type)
+
+#define gv_fetchpvs(namebeg, flags, sv_type) \
+ Perl_gv_fetchpvn_flags(aTHX_ STR_WITH_LEN(namebeg), flags, sv_type)
+#define gv_fetchpvn gv_fetchpvn_flags
#define sv_catxmlpvs(dsv, str, utf8) \
Perl_sv_catxmlpvn(aTHX_ dsv, STR_WITH_LEN(str), utf8)
/*
=for apidoc_section Versioning
=for apidoc AmR|bool|PERL_VERSION_EQ|const U8 major|const U8 minor|const U8 patch
+=for apidoc_item PERL_VERSION_NE
+=for apidoc_item PERL_VERSION_LT
+=for apidoc_item PERL_VERSION_LE
+=for apidoc_item PERL_VERSION_GT
+=for apidoc_item PERL_VERSION_GE
Returns whether or not the perl currently being compiled has the specified
relationship to the perl given by the parameters. For example,
Note that this is usable in making compile-time decisions
-The possible comparisons are C<PERL_VERSION_EQ>, C<PERL_VERSION_NE>,
-C<PERL_VERSION_GE>, C<PERL_VERSION_GT>, C<PERL_VERSION_LE>, and
-C<PERL_VERSION_LT>.
-
You may use the special value '*' for the final number to mean ALL possible
values for it. Thus,
#if PERL_VERSION_LE(5,9,'*')
-=for apidoc AmRh|bool|PERL_VERSION_NE|const U8 major|const U8 minor|const U8 patch
-=for apidoc AmRh|bool|PERL_VERSION_GE|const U8 major|const U8 minor|const U8 patch
-=for apidoc AmRh|bool|PERL_VERSION_GT|const U8 major|const U8 minor|const U8 patch
-=for apidoc AmRh|bool|PERL_VERSION_LE|const U8 major|const U8 minor|const U8 patch
-=for apidoc AmRh|bool|PERL_VERSION_LT|const U8 major|const U8 minor|const U8 patch
-
=cut
*/
return FALSE, at the discretion of the implementation, and subject to change in
future releases.
-=for apidoc Am|bool|isALPHA|int ch
-=for apidoc_item ||isALPHA_A|int ch
-=for apidoc_item ||isALPHA_L1|int ch
-=for apidoc_item ||isALPHA_uvchr|int ch
+=for apidoc Am|bool|isALPHA|UV ch
+=for apidoc_item ||isALPHA_A|UV ch
+=for apidoc_item ||isALPHA_L1|UV ch
+=for apidoc_item ||isALPHA_uvchr|UV ch
=for apidoc_item ||isALPHA_utf8_safe|U8 * s|U8 * end
=for apidoc_item ||isALPHA_utf8|U8 * s|U8 * end
-=for apidoc_item ||isALPHA_LC|int ch
-=for apidoc_item ||isALPHA_LC_uvchr|int ch
+=for apidoc_item ||isALPHA_LC|UV ch
+=for apidoc_item ||isALPHA_LC_uvchr|UV ch
=for apidoc_item ||isALPHA_LC_utf8_safe|U8 * s| U8 *end
Returns a boolean indicating whether the specified input is one of C<[A-Za-z]>,
analogous to C<m/[[:alpha:]]/>.
=cut
-Here and below, we add the protoypes of these macros for downstream programs
+Here and below, we add the prototypes of these macros for downstream programs
that would be interested in them, such as Devel::PPPort
-=for apidoc Am|bool|isALPHANUMERIC|int ch
-=for apidoc_item ||isALPHANUMERIC_A|int ch
-=for apidoc_item ||isALPHANUMERIC_L1|int ch
-=for apidoc_item ||isALPHANUMERIC_uvchr|int ch
+=for apidoc Am|bool|isALPHANUMERIC|UV ch
+=for apidoc_item ||isALPHANUMERIC_A|UV ch
+=for apidoc_item ||isALPHANUMERIC_L1|UV ch
+=for apidoc_item ||isALPHANUMERIC_uvchr|UV ch
=for apidoc_item ||isALPHANUMERIC_utf8_safe|U8 * s|U8 * end
=for apidoc_item ||isALPHANUMERIC_utf8|U8 * s|U8 * end
-=for apidoc_item ||isALPHANUMERIC_LC|int ch
-=for apidoc_item ||isALPHANUMERIC_LC_uvchr|int ch
+=for apidoc_item ||isALPHANUMERIC_LC|UV ch
+=for apidoc_item ||isALPHANUMERIC_LC_uvchr|UV ch
=for apidoc_item ||isALPHANUMERIC_LC_utf8_safe|U8 * s| U8 *end
-=for apidoc_item ||isALNUMC|int ch
-=for apidoc_item ||isALNUMC_A|int ch
-=for apidoc_item ||isALNUMC_L1|int ch
-=for apidoc_item ||isALNUMC_LC|int ch
-=for apidoc_item ||isALNUMC_LC_uvchr|int ch
+=for apidoc_item ||isALNUMC|UV ch
+=for apidoc_item ||isALNUMC_A|UV ch
+=for apidoc_item ||isALNUMC_L1|UV ch
+=for apidoc_item ||isALNUMC_LC|UV ch
+=for apidoc_item ||isALNUMC_LC_uvchr|UV ch
Returns a boolean indicating whether the specified character is one of
C<[A-Za-z0-9]>, analogous to C<m/[[:alnum:]]/>.
See the L<top of this section|/Character classification> for an explanation of
C<isALNUMC_A>, C<isALNUMC_L1>
C<isALNUMC_LC>, and C<isALNUMC_LC_uvchr>.
-=for apidoc Am|bool|isASCII|int ch
-=for apidoc_item ||isASCII_A|int ch
-=for apidoc_item ||isASCII_L1|int ch
-=for apidoc_item ||isASCII_uvchr|int ch
+=for apidoc Am|bool|isASCII|UV ch
+=for apidoc_item ||isASCII_A|UV ch
+=for apidoc_item ||isASCII_L1|UV ch
+=for apidoc_item ||isASCII_uvchr|UV ch
=for apidoc_item ||isASCII_utf8_safe|U8 * s|U8 * end
=for apidoc_item ||isASCII_utf8|U8 * s|U8 * end
-=for apidoc_item ||isASCII_LC|int ch
-=for apidoc_item ||isASCII_LC_uvchr|int ch
+=for apidoc_item ||isASCII_LC|UV ch
+=for apidoc_item ||isASCII_LC_uvchr|UV ch
=for apidoc_item ||isASCII_LC_utf8_safe|U8 * s| U8 *end
Returns a boolean indicating whether the specified character is one of the 128
characters in the ASCII character set, analogous to C<m/[[:ascii:]]/>.
byte in any string encoded or not in UTF-8. And similarly C<isASCII_utf8> and
C<isASCII_utf8_safe> will work properly on any string encoded or not in UTF-8.
-=for apidoc Am|bool|isBLANK|int ch
-=for apidoc_item ||isBLANK_A|int ch
-=for apidoc_item ||isBLANK_L1|int ch
-=for apidoc_item ||isBLANK_uvchr|int ch
+=for apidoc Am|bool|isBLANK|UV ch
+=for apidoc_item ||isBLANK_A|UV ch
+=for apidoc_item ||isBLANK_L1|UV ch
+=for apidoc_item ||isBLANK_uvchr|UV ch
=for apidoc_item ||isBLANK_utf8_safe|U8 * s|U8 * end
=for apidoc_item ||isBLANK_utf8|U8 * s|U8 * end
-=for apidoc_item ||isBLANK_LC|int ch
-=for apidoc_item ||isBLANK_LC_uvchr|int ch
+=for apidoc_item ||isBLANK_LC|UV ch
+=for apidoc_item ||isBLANK_LC_uvchr|UV ch
=for apidoc_item ||isBLANK_LC_utf8_safe|U8 * s| U8 *end
Returns a boolean indicating whether the specified character is a
character considered to be a blank, analogous to C<m/[[:blank:]]/>.
C<isblank()>. In these cases, the variants whose names contain C<LC> are
the same as the corresponding ones without.
-=for apidoc Am|bool|isCNTRL|int ch
-=for apidoc_item ||isCNTRL_A|int ch
-=for apidoc_item ||isCNTRL_L1|int ch
-=for apidoc_item ||isCNTRL_uvchr|int ch
+=for apidoc Am|bool|isCNTRL|UV ch
+=for apidoc_item ||isCNTRL_A|UV ch
+=for apidoc_item ||isCNTRL_L1|UV ch
+=for apidoc_item ||isCNTRL_uvchr|UV ch
=for apidoc_item ||isCNTRL_utf8_safe|U8 * s|U8 * end
=for apidoc_item ||isCNTRL_utf8|U8 * s|U8 * end
-=for apidoc_item ||isCNTRL_LC|int ch
-=for apidoc_item ||isCNTRL_LC_uvchr|int ch
+=for apidoc_item ||isCNTRL_LC|UV ch
+=for apidoc_item ||isCNTRL_LC_uvchr|UV ch
=for apidoc_item ||isCNTRL_LC_utf8_safe|U8 * s| U8 *end
Returns a boolean indicating whether the specified character is a
the variants.
On EBCDIC platforms, you almost always want to use the C<isCNTRL_L1> variant.
-=for apidoc Am|bool|isDIGIT|int ch
-=for apidoc_item ||isDIGIT_A|int ch
-=for apidoc_item ||isDIGIT_L1|int ch
-=for apidoc_item ||isDIGIT_uvchr|int ch
+=for apidoc Am|bool|isDIGIT|UV ch
+=for apidoc_item ||isDIGIT_A|UV ch
+=for apidoc_item ||isDIGIT_L1|UV ch
+=for apidoc_item ||isDIGIT_uvchr|UV ch
=for apidoc_item ||isDIGIT_utf8_safe|U8 * s|U8 * end
=for apidoc_item ||isDIGIT_utf8|U8 * s|U8 * end
-=for apidoc_item ||isDIGIT_LC|int ch
-=for apidoc_item ||isDIGIT_LC_uvchr|int ch
+=for apidoc_item ||isDIGIT_LC|UV ch
+=for apidoc_item ||isDIGIT_LC_uvchr|UV ch
=for apidoc_item ||isDIGIT_LC_utf8_safe|U8 * s| U8 *end
Returns a boolean indicating whether the specified character is a
See the L<top of this section|/Character classification> for an explanation of
the variants.
-=for apidoc Am|bool|isGRAPH|int ch
-=for apidoc_item ||isGRAPH_A|int ch
-=for apidoc_item ||isGRAPH_L1|int ch
-=for apidoc_item ||isGRAPH_uvchr|int ch
+=for apidoc Am|bool|isGRAPH|UV ch
+=for apidoc_item ||isGRAPH_A|UV ch
+=for apidoc_item ||isGRAPH_L1|UV ch
+=for apidoc_item ||isGRAPH_uvchr|UV ch
=for apidoc_item ||isGRAPH_utf8_safe|U8 * s|U8 * end
=for apidoc_item ||isGRAPH_utf8|U8 * s|U8 * end
-=for apidoc_item ||isGRAPH_LC|int ch
-=for apidoc_item ||isGRAPH_LC_uvchr|int ch
+=for apidoc_item ||isGRAPH_LC|UV ch
+=for apidoc_item ||isGRAPH_LC_uvchr|UV ch
=for apidoc_item ||isGRAPH_LC_utf8_safe|U8 * s| U8 *end
Returns a boolean indicating whether the specified character is a
graphic character, analogous to C<m/[[:graph:]]/>.
See the L<top of this section|/Character classification> for an explanation of
the variants.
-=for apidoc Am|bool|isLOWER|int ch
-=for apidoc_item ||isLOWER_A|int ch
-=for apidoc_item ||isLOWER_L1|int ch
-=for apidoc_item ||isLOWER_uvchr|int ch
+=for apidoc Am|bool|isLOWER|UV ch
+=for apidoc_item ||isLOWER_A|UV ch
+=for apidoc_item ||isLOWER_L1|UV ch
+=for apidoc_item ||isLOWER_uvchr|UV ch
=for apidoc_item ||isLOWER_utf8_safe|U8 * s|U8 * end
=for apidoc_item ||isLOWER_utf8|U8 * s|U8 * end
-=for apidoc_item ||isLOWER_LC|int ch
-=for apidoc_item ||isLOWER_LC_uvchr|int ch
+=for apidoc_item ||isLOWER_LC|UV ch
+=for apidoc_item ||isLOWER_LC_uvchr|UV ch
=for apidoc_item ||isLOWER_LC_utf8_safe|U8 * s| U8 *end
Returns a boolean indicating whether the specified character is a
lowercase character, analogous to C<m/[[:lower:]]/>.
See the L<top of this section|/Character classification> for an explanation of
the variants
-=for apidoc Am|bool|isOCTAL|int ch
-=for apidoc_item ||isOCTAL_A|int ch
-=for apidoc_item ||isOCTAL_L1|int ch
+=for apidoc Am|bool|isOCTAL|UV ch
+=for apidoc_item ||isOCTAL_A|UV ch
+=for apidoc_item ||isOCTAL_L1|UV ch
Returns a boolean indicating whether the specified character is an
octal digit, [0-7].
The only two variants are C<isOCTAL_A> and C<isOCTAL_L1>; each is identical to
C<isOCTAL>.
-=for apidoc Am|bool|isPUNCT|int ch
-=for apidoc_item ||isPUNCT_A|int ch
-=for apidoc_item ||isPUNCT_L1|int ch
-=for apidoc_item ||isPUNCT_uvchr|int ch
+=for apidoc Am|bool|isPUNCT|UV ch
+=for apidoc_item ||isPUNCT_A|UV ch
+=for apidoc_item ||isPUNCT_L1|UV ch
+=for apidoc_item ||isPUNCT_uvchr|UV ch
=for apidoc_item ||isPUNCT_utf8_safe|U8 * s|U8 * end
=for apidoc_item ||isPUNCT_utf8|U8 * s|U8 * end
-=for apidoc_item ||isPUNCT_LC|int ch
-=for apidoc_item ||isPUNCT_LC_uvchr|int ch
+=for apidoc_item ||isPUNCT_LC|UV ch
+=for apidoc_item ||isPUNCT_LC_uvchr|UV ch
=for apidoc_item ||isPUNCT_LC_utf8_safe|U8 * s| U8 *end
Returns a boolean indicating whether the specified character is a
punctuation character, analogous to C<m/[[:punct:]]/>.
See the L<top of this section|/Character classification> for an explanation of
the variants.
-=for apidoc Am|bool|isSPACE|int ch
-=for apidoc_item ||isSPACE_A|int ch
-=for apidoc_item ||isSPACE_L1|int ch
-=for apidoc_item ||isSPACE_uvchr|int ch
+=for apidoc Am|bool|isSPACE|UV ch
+=for apidoc_item ||isSPACE_A|UV ch
+=for apidoc_item ||isSPACE_L1|UV ch
+=for apidoc_item ||isSPACE_uvchr|UV ch
=for apidoc_item ||isSPACE_utf8_safe|U8 * s|U8 * end
=for apidoc_item ||isSPACE_utf8|U8 * s|U8 * end
-=for apidoc_item ||isSPACE_LC|int ch
-=for apidoc_item ||isSPACE_LC_uvchr|int ch
+=for apidoc_item ||isSPACE_LC|UV ch
+=for apidoc_item ||isSPACE_LC_uvchr|UV ch
=for apidoc_item ||isSPACE_LC_utf8_safe|U8 * s| U8 *end
Returns a boolean indicating whether the specified character is a
whitespace character. This is analogous
See the L<top of this section|/Character classification> for an explanation of
the variants.
-=for apidoc Am|bool|isPSXSPC|int ch
-=for apidoc_item ||isPSXSPC_A|int ch
-=for apidoc_item ||isPSXSPC_L1|int ch
-=for apidoc_item ||isPSXSPC_uvchr|int ch
+=for apidoc Am|bool|isPSXSPC|UV ch
+=for apidoc_item ||isPSXSPC_A|UV ch
+=for apidoc_item ||isPSXSPC_L1|UV ch
+=for apidoc_item ||isPSXSPC_uvchr|UV ch
=for apidoc_item ||isPSXSPC_utf8_safe|U8 * s|U8 * end
=for apidoc_item ||isPSXSPC_utf8|U8 * s|U8 * end
-=for apidoc_item ||isPSXSPC_LC|int ch
-=for apidoc_item ||isPSXSPC_LC_uvchr|int ch
+=for apidoc_item ||isPSXSPC_LC|UV ch
+=for apidoc_item ||isPSXSPC_LC_uvchr|UV ch
=for apidoc_item ||isPSXSPC_LC_utf8_safe|U8 * s| U8 *end
(short for Posix Space)
Starting in 5.18, this is identical in all its forms to the
See the L<top of this section|/Character classification> for an explanation of
the variants.
-=for apidoc Am|bool|isUPPER|int ch
-=for apidoc_item ||isUPPER_A|int ch
-=for apidoc_item ||isUPPER_L1|int ch
-=for apidoc_item ||isUPPER_uvchr|int ch
+=for apidoc Am|bool|isUPPER|UV ch
+=for apidoc_item ||isUPPER_A|UV ch
+=for apidoc_item ||isUPPER_L1|UV ch
+=for apidoc_item ||isUPPER_uvchr|UV ch
=for apidoc_item ||isUPPER_utf8_safe|U8 * s|U8 * end
=for apidoc_item ||isUPPER_utf8|U8 * s|U8 * end
-=for apidoc_item ||isUPPER_LC|int ch
-=for apidoc_item ||isUPPER_LC_uvchr|int ch
+=for apidoc_item ||isUPPER_LC|UV ch
+=for apidoc_item ||isUPPER_LC_uvchr|UV ch
=for apidoc_item ||isUPPER_LC_utf8_safe|U8 * s| U8 *end
Returns a boolean indicating whether the specified character is an
uppercase character, analogous to C<m/[[:upper:]]/>.
See the L<top of this section|/Character classification> for an explanation of
the variants.
-=for apidoc Am|bool|isPRINT|int ch
-=for apidoc_item ||isPRINT_A|int ch
-=for apidoc_item ||isPRINT_L1|int ch
-=for apidoc_item ||isPRINT_uvchr|int ch
+=for apidoc Am|bool|isPRINT|UV ch
+=for apidoc_item ||isPRINT_A|UV ch
+=for apidoc_item ||isPRINT_L1|UV ch
+=for apidoc_item ||isPRINT_uvchr|UV ch
=for apidoc_item ||isPRINT_utf8_safe|U8 * s|U8 * end
=for apidoc_item ||isPRINT_utf8|U8 * s|U8 * end
-=for apidoc_item ||isPRINT_LC|int ch
-=for apidoc_item ||isPRINT_LC_uvchr|int ch
+=for apidoc_item ||isPRINT_LC|UV ch
+=for apidoc_item ||isPRINT_LC_uvchr|UV ch
=for apidoc_item ||isPRINT_LC_utf8_safe|U8 * s| U8 *end
Returns a boolean indicating whether the specified character is a
printable character, analogous to C<m/[[:print:]]/>.
See the L<top of this section|/Character classification> for an explanation of
the variants.
-=for apidoc Am|bool|isWORDCHAR|int ch
-=for apidoc_item ||isWORDCHAR_A|int ch
-=for apidoc_item ||isWORDCHAR_L1|int ch
-=for apidoc_item ||isWORDCHAR_uvchr|int ch
+=for apidoc Am|bool|isWORDCHAR|UV ch
+=for apidoc_item ||isWORDCHAR_A|UV ch
+=for apidoc_item ||isWORDCHAR_L1|UV ch
+=for apidoc_item ||isWORDCHAR_uvchr|UV ch
=for apidoc_item ||isWORDCHAR_utf8_safe|U8 * s|U8 * end
=for apidoc_item ||isWORDCHAR_utf8|U8 * s|U8 * end
-=for apidoc_item ||isWORDCHAR_LC|int ch
-=for apidoc_item ||isWORDCHAR_LC_uvchr|int ch
+=for apidoc_item ||isWORDCHAR_LC|UV ch
+=for apidoc_item ||isWORDCHAR_LC_uvchr|UV ch
=for apidoc_item ||isWORDCHAR_LC_utf8_safe|U8 * s| U8 *end
-=for apidoc_item ||isALNUM|int ch
-=for apidoc_item ||isALNUM_A|int ch
-=for apidoc_item ||isALNUM_LC|int ch
-=for apidoc_item ||isALNUM_LC_uvchr|int ch
+=for apidoc_item ||isALNUM|UV ch
+=for apidoc_item ||isALNUM_A|UV ch
+=for apidoc_item ||isALNUM_LC|UV ch
+=for apidoc_item ||isALNUM_LC_uvchr|UV ch
Returns a boolean indicating whether the specified character is a character
that is a word character, analogous to what C<m/\w/> and C<m/[[:word:]]/> match
in a regular expression. A word character is an alphabetic character, a
C<isWORDCHAR_LC_utf8_safe> are also as described there, but additionally
include the platform's native underscore.
-=for apidoc Am|bool|isXDIGIT|int ch
-=for apidoc_item ||isXDIGIT_A|int ch
-=for apidoc_item ||isXDIGIT_L1|int ch
-=for apidoc_item ||isXDIGIT_uvchr|int ch
+=for apidoc Am|bool|isXDIGIT|UV ch
+=for apidoc_item ||isXDIGIT_A|UV ch
+=for apidoc_item ||isXDIGIT_L1|UV ch
+=for apidoc_item ||isXDIGIT_uvchr|UV ch
=for apidoc_item ||isXDIGIT_utf8_safe|U8 * s|U8 * end
=for apidoc_item ||isXDIGIT_utf8|U8 * s|U8 * end
-=for apidoc_item ||isXDIGIT_LC|int ch
-=for apidoc_item ||isXDIGIT_LC_uvchr|int ch
+=for apidoc_item ||isXDIGIT_LC|UV ch
+=for apidoc_item ||isXDIGIT_LC_uvchr|UV ch
=for apidoc_item ||isXDIGIT_LC_utf8_safe|U8 * s| U8 *end
Returns a boolean indicating whether the specified character is a hexadecimal
digit. In the ASCII range these are C<[0-9A-Fa-f]>. Variants C<isXDIGIT_A()>
See the L<top of this section|/Character classification> for an explanation of
the variants.
-=for apidoc Am|bool|isIDFIRST|int ch
-=for apidoc_item ||isIDFIRST_A|int ch
-=for apidoc_item ||isIDFIRST_L1|int ch
-=for apidoc_item ||isIDFIRST_uvchr|int ch
+=for apidoc Am|bool|isIDFIRST|UV ch
+=for apidoc_item ||isIDFIRST_A|UV ch
+=for apidoc_item ||isIDFIRST_L1|UV ch
+=for apidoc_item ||isIDFIRST_uvchr|UV ch
=for apidoc_item ||isIDFIRST_utf8_safe|U8 * s|U8 * end
=for apidoc_item ||isIDFIRST_utf8|U8 * s|U8 * end
-=for apidoc_item ||isIDFIRST_LC|int ch
-=for apidoc_item ||isIDFIRST_LC_uvchr|int ch
+=for apidoc_item ||isIDFIRST_LC|UV ch
+=for apidoc_item ||isIDFIRST_LC_uvchr|UV ch
=for apidoc_item ||isIDFIRST_LC_utf8_safe|U8 * s| U8 *end
Returns a boolean indicating whether the specified character can be the first
character of an identifier. This is very close to, but not quite the same as
See the L<top of this section|/Character classification> for an explanation of
the variants.
-=for apidoc Am|bool|isIDCONT|int ch
-=for apidoc_item ||isIDCONT_A|int ch
-=for apidoc_item ||isIDCONT_L1|int ch
-=for apidoc_item ||isIDCONT_uvchr|int ch
+=for apidoc Am|bool|isIDCONT|UV ch
+=for apidoc_item ||isIDCONT_A|UV ch
+=for apidoc_item ||isIDCONT_L1|UV ch
+=for apidoc_item ||isIDCONT_uvchr|UV ch
=for apidoc_item ||isIDCONT_utf8_safe|U8 * s|U8 * end
=for apidoc_item ||isIDCONT_utf8|U8 * s|U8 * end
-=for apidoc_item ||isIDCONT_LC|int ch
-=for apidoc_item ||isIDCONT_LC_uvchr|int ch
+=for apidoc_item ||isIDCONT_LC|UV ch
+=for apidoc_item ||isIDCONT_LC_uvchr|UV ch
=for apidoc_item ||isIDCONT_LC_utf8_safe|U8 * s| U8 *end
Returns a boolean indicating whether the specified character can be the
second or succeeding character of an identifier. This is very close to, but
C<toFOLD_utf8_safe> is now just a different spelling of plain C<toFOLD_utf8>
-=for apidoc Am|U8|toLOWER|U8 ch
-Converts the specified character to lowercase. If the input is anything but an
-ASCII uppercase character, that input character itself is returned. Variant
-C<toLOWER_A> is equivalent.
-
-=for apidoc Am|U8|toLOWER_L1|U8 ch
-Converts the specified Latin1 character to lowercase. The results are
-undefined if the input doesn't fit in a byte.
-
-=for apidoc Am|U8|toLOWER_LC|U8 ch
-Converts the specified character to lowercase using the current locale's rules,
-if possible; otherwise returns the input character itself.
-
-=for apidoc Am|UV|toLOWER_uvchr|UV cp|U8* s|STRLEN* lenp
-Converts the code point C<cp> to its lowercase version, and
-stores that in UTF-8 in C<s>, and its length in bytes in C<lenp>. The code
-point is interpreted as native if less than 256; otherwise as Unicode. Note
-that the buffer pointed to by C<s> needs to be at least C<UTF8_MAXBYTES_CASE+1>
-bytes since the lowercase version may be longer than the original character.
-
-The first code point of the lowercased version is returned
-(but note, as explained at L<the top of this section|/Character case
-changing>, that there may be more).
-
-=for apidoc Am|UV|toLOWER_utf8|U8* p|U8* e|U8* s|STRLEN* lenp
-=for apidoc_item toLOWER_utf8_safe
-Converts the first UTF-8 encoded character in the sequence starting at C<p> and
-extending no further than S<C<e - 1>> to its lowercase version, and
-stores that in UTF-8 in C<s>, and its length in bytes in C<lenp>. Note
-that the buffer pointed to by C<s> needs to be at least C<UTF8_MAXBYTES_CASE+1>
-bytes since the lowercase version may be longer than the original character.
-
-The first code point of the lowercased version is returned
-(but note, as explained at L<the top of this section|/Character case
-changing>, that there may be more).
-It will not attempt to read beyond S<C<e - 1>>, provided that the constraint
-S<C<s E<lt> e>> is true (this is asserted for in C<-DDEBUGGING> builds). If
-the UTF-8 for the input character is malformed in some way, the program may
-croak, or the function may return the REPLACEMENT CHARACTER, at the discretion
-of the implementation, and subject to change in future releases.
-
-C<toLOWER_utf8_safe> is now just a different spelling of plain C<toLOWER_utf8>
+=for apidoc Am|UV|toLOWER|UV cp
+=for apidoc_item |UV|toLOWER_A|UV cp
+=for apidoc_item |UV|toLOWER_L1|UV cp
+=for apidoc_item |UV|toLOWER_LATIN1|UV cp
+=for apidoc_item |UV|toLOWER_LC|UV cp
+=for apidoc_item |UV|toLOWER_uvchr|UV cp|U8* s|STRLEN* lenp
+=for apidoc_item |UV|toLOWER_utf8|U8* p|U8* e|U8* s|STRLEN* lenp
+=for apidoc_item |UV|toLOWER_utf8_safe|U8* p|U8* e|U8* s|STRLEN* lenp
+
+These all return the lowercase of a character. The differences are what domain
+they operate on, and whether the input is specified as a code point (those
+forms with a C<cp> parameter) or as a UTF-8 string (the others). In the latter
+case, the code point to use is the first one in the buffer of UTF-8 encoded
+code points, delineated by the arguments S<C<p .. e - 1>>.
+
+C<toLOWER> and C<toLOWER_A> are synonyms of each other. They return the
+lowercase of any uppercase ASCII-range code point. All other inputs are
+returned unchanged. Since these are macros, the input type may be any integral
+one, and the output will occupy the same number of bits as the input.
+
+C<toLOWER_L1> and C<toLOWER_LATIN1> are synonyms of each other. They behave
+identically as C<toLOWER> for ASCII-range input. But additionally will return
+the lowercase of any uppercase code point in the entire 0..255 range, assuming
+a Latin-1 encoding (or the EBCDIC equivalent on such platforms).
+
+C<toLOWER_LC> returns the lowercase of the input code point according to the
+rules of the current POSIX locale. Input code points outside the range 0..255
+are returned unchanged.
+
+C<toLOWER_uvchr> returns the lowercase of any Unicode code point. The return
+value is identical to that of C<toLOWER_L1> for input code points in the 0..255
+range. The lowercase of the vast majority of Unicode code points is the same
+as the code point itself. For these, and for code points above the legal
+Unicode maximum, this returns the input code point unchanged. It additionally
+stores the UTF-8 of the result into the buffer beginning at C<s>, and its
+length in bytes into C<*lenp>. The caller must have made C<s> large enough to
+contain at least C<UTF8_MAXBYTES_CASE+1> bytes to avoid possible overflow.
+
+NOTE: the lowercase of a code point may be more than one code point. The
+return value of this function is only the first of these. The entire lowercase
+is returned in C<s>. To determine if the result is more than a single code
+point, you can do something like this:
+
+ uc = toLOWER_uvchr(cp, s, &len);
+ if (len > UTF8SKIP(s)) { is multiple code points }
+ else { is a single code point }
+
+C<toLOWER_utf8> and C<toLOWER_utf8_safe> are synonyms of each other. The only
+difference between these and C<toLOWER_uvchr> is that the source for these is
+encoded in UTF-8, instead of being a code point. It is passed as a buffer
+starting at C<p>, with C<e> pointing to one byte beyond its end. The C<p>
+buffer may certainly contain more than one code point; but only the first one
+(up through S<C<e - 1>>) is examined. If the UTF-8 for the input character is
+malformed in some way, the program may croak, or the function may return the
+REPLACEMENT CHARACTER, at the discretion of the implementation, and subject to
+change in future releases.
=for apidoc Am|U8|toTITLE|U8 ch
Converts the specified character to titlecase. If the input is anything but an
=for apidoc AmnU|void|WIDEST_UTYPE
Yields the widest unsigned integer type on the platform, currently either
-C<U32> or C<64>. This can be used in declarations such as
+C<U32> or C<U64>. This can be used in declarations such as
WIDEST_UTYPE my_uv;
#define OCTAL_VALUE(c) (__ASSERT_(isOCTAL(c)) (7 & (c)))
/* Efficiently returns a boolean as to if two native characters are equivalent
- * case-insenstively. At least one of the characters must be one of [A-Za-z];
+ * case-insensitively. At least one of the characters must be one of [A-Za-z];
* the ALPHA in the name is to remind you of that. This is asserted() in
* DEBUGGING builds. Because [A-Za-z] are invariant under UTF-8, this macro
* works (on valid input) for both non- and UTF-8-encoded bytes.
https://perl5.git.perl.org / perl5.git / blobdiff