/*
=head1 Handy Values
-=for apidoc AmU||Nullch
+=for apidoc AmnU||Nullch
Null character pointer. (No longer available when C<PERL_CORE> is
defined.)
-=for apidoc AmU||Nullsv
+=for apidoc AmnU||Nullsv
Null SV pointer. (No longer available when C<PERL_CORE> is defined.)
=cut
# define HAS_BOOL 1
#endif
-/* cast-to-bool. A simple (bool) cast may not do the right thing: if bool is
- * defined as char for example, then the cast from int is
- * implementation-defined (bool)!!(cbool) in a ternary triggers a bug in xlc on
- * AIX */
+/*
+=for apidoc Am|bool|cBOOL|bool expr
+
+Cast-to-bool. A simple S<C<(bool) I<expr>>> cast may not do the right thing:
+if C<bool> is defined as C<char>, for example, then the cast from C<int> is
+implementation-defined.
+
+C<(bool)!!(cbool)> in a ternary triggers a bug in xlc on AIX
+
+=cut
+*/
#define cBOOL(cbool) ((cbool) ? (bool)1 : (bool)0)
/* Try to figure out __func__ or __FUNCTION__ equivalent, if any.
typedef I32TYPE I32;
typedef U32TYPE U32;
-#ifdef HAS_QUAD
+#ifdef QUADKIND
typedef I64TYPE I64;
typedef U64TYPE U64;
#endif
-/* INT64_C/UINT64_C are C99 from <stdint.h> (so they will not be
- * available in strict C89 mode), but they are nice, so let's define
- * them if necessary. */
-#if defined(HAS_QUAD)
-# undef PeRl_INT64_C
-# undef PeRl_UINT64_C
-/* Prefer the native integer types (int and long) over long long
- * (which is not C89) and Win32-specific __int64. */
-# if QUADKIND == QUAD_IS_INT && INTSIZE == 8
-# define PeRl_INT64_C(c) (c)
-# define PeRl_UINT64_C(c) CAT2(c,U)
-# endif
-# if QUADKIND == QUAD_IS_LONG && LONGSIZE == 8
-# define PeRl_INT64_C(c) CAT2(c,L)
-# define PeRl_UINT64_C(c) CAT2(c,UL)
-# endif
-# if QUADKIND == QUAD_IS_LONG_LONG && defined(HAS_LONG_LONG)
-# define PeRl_INT64_C(c) CAT2(c,LL)
-# define PeRl_UINT64_C(c) CAT2(c,ULL)
-# endif
-# if QUADKIND == QUAD_IS___INT64
-# define PeRl_INT64_C(c) CAT2(c,I64)
-# define PeRl_UINT64_C(c) CAT2(c,UI64)
-# endif
-# ifndef PeRl_INT64_C
-# define PeRl_INT64_C(c) ((I64)(c)) /* last resort */
-# define PeRl_UINT64_C(c) ((U64)(c))
-# endif
-/* In OS X the INT64_C/UINT64_C are defined with LL/ULL, which will
- * not fly with C89-pedantic gcc, so let's undefine them first so that
- * we can redefine them with our native integer preferring versions. */
-# if defined(PERL_DARWIN) && defined(PERL_GCC_PEDANTIC)
-# undef INT64_C
-# undef UINT64_C
-# endif
-# ifndef INT64_C
-# define INT64_C(c) PeRl_INT64_C(c)
-# endif
-# ifndef UINT64_C
-# define UINT64_C(c) PeRl_UINT64_C(c)
-# endif
-#endif
-
#if defined(UINT8_MAX) && defined(INT16_MAX) && defined(INT32_MAX)
/* I8_MAX and I8_MIN constants are not defined, as I8 is an ambiguous type.
#endif
-/* log(2) is pretty close to 0.30103, just in case anyone is grepping for it */
-#define BIT_DIGITS(N) (((N)*146)/485 + 1) /* log2(10) =~ 146/485 */
+/* These C99 typedefs are useful sometimes for, say, loop variables whose
+ * maximum values are small, but for which speed trumps size. If we have a C99
+ * compiler, use that. Otherwise, a plain 'int' should be good enough.
+ *
+ * Restrict these to core for now until we are more certain this is a good
+ * idea. */
+#if defined(PERL_CORE) || defined(PERL_EXT)
+# ifdef I_STDINT
+ typedef int_fast8_t PERL_INT_FAST8_T;
+ typedef uint_fast8_t PERL_UINT_FAST8_T;
+ typedef int_fast16_t PERL_INT_FAST16_T;
+ typedef uint_fast16_t PERL_UINT_FAST16_T;
+# else
+ typedef int PERL_INT_FAST8_T;
+ typedef unsigned int PERL_UINT_FAST8_T;
+ typedef int PERL_INT_FAST16_T;
+ typedef unsigned int PERL_UINT_FAST16_T;
+# endif
+#endif
+
+/* log(2) (i.e., log base 10 of 2) is pretty close to 0.30103, just in case
+ * anyone is grepping for it */
+#define BIT_DIGITS(N) (((N)*146)/485 + 1) /* log10(2) =~ 146/485 */
#define TYPE_DIGITS(T) BIT_DIGITS(sizeof(T) * 8)
#define TYPE_CHARS(T) (TYPE_DIGITS(T) + 2) /* sign, NUL */
# endif
#endif
-/* This is a helper macro to avoid preprocessor issues, replaced by nothing
- * unless under DEBUGGING, where it expands to an assert of its argument,
- * followed by a comma (hence the comma operator). If we just used a straight
- * assert(), we would get a comma with nothing before it when not DEBUGGING.
- *
- * We also use empty definition under Coverity since the __ASSERT__
- * checks often check for things that Really Cannot Happen, and Coverity
- * detects that and gets all excited. */
+/* Returns a boolean as to whether the input unsigned number is a power of 2
+ * (2**0, 2**1, etc). In other words if it has just a single bit set.
+ * If not, subtracting 1 would leave the uppermost bit set, so the & would
+ * yield non-zero */
+#if defined(PERL_CORE) || defined(PERL_EXT)
+# define isPOWER_OF_2(n) ((n) && ((n) & ((n)-1)) == 0)
+#endif
+
+/*
+=for apidoc Am|void|__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,
+followed by a comma (hence the comma operator). If we just used a straight
+assert(), we would get a comma with nothing before it when not DEBUGGING.
+
+=cut
+
+We also use empty definition under Coverity since the __ASSERT__
+checks often check for things that Really Cannot Happen, and Coverity
+detects that and gets all excited. */
#if defined(DEBUGGING) && !defined(__COVERITY__)
# define __ASSERT_(statement) assert(statement),
#endif
/*
-=head1 SV-Body Allocation
+=head1 SV Manipulation Functions
-=for apidoc Ama|SV*|newSVpvs|const char* s
-Like C<newSVpvn>, but takes a C<NUL>-terminated literal string instead of a
+=for apidoc Ama|SV*|newSVpvs|"literal string"
+Like C<newSVpvn>, but takes a literal string instead of a
string/length pair.
-=for apidoc Ama|SV*|newSVpvs_flags|const char* s|U32 flags
-Like C<newSVpvn_flags>, but takes a C<NUL>-terminated literal string instead of
+=for apidoc Ama|SV*|newSVpvs_flags|"literal string"|U32 flags
+Like C<newSVpvn_flags>, but takes a literal string instead of
a string/length pair.
-=for apidoc Ama|SV*|newSVpvs_share|const char* s
-Like C<newSVpvn_share>, but takes a C<NUL>-terminated literal string instead of
+=for apidoc Ama|SV*|newSVpvs_share|"literal string"
+Like C<newSVpvn_share>, but takes a literal string instead of
a string/length pair and omits the hash parameter.
-=for apidoc Am|void|sv_catpvs_flags|SV* sv|const char* s|I32 flags
-Like C<sv_catpvn_flags>, but takes a C<NUL>-terminated literal string instead
+=for apidoc Am|void|sv_catpvs_flags|SV* sv|"literal string"|I32 flags
+Like C<sv_catpvn_flags>, but takes a literal string instead
of a string/length pair.
-=for apidoc Am|void|sv_catpvs_nomg|SV* sv|const char* s
-Like C<sv_catpvn_nomg>, but takes a C<NUL>-terminated literal string instead of
+=for apidoc Am|void|sv_catpvs_nomg|SV* sv|"literal string"
+Like C<sv_catpvn_nomg>, but takes a literal string instead of
a string/length pair.
-=for apidoc Am|void|sv_catpvs|SV* sv|const char* s
-Like C<sv_catpvn>, but takes a C<NUL>-terminated literal string instead of a
+=for apidoc Am|void|sv_catpvs|SV* sv|"literal string"
+Like C<sv_catpvn>, but takes a literal string instead of a
string/length pair.
-=for apidoc Am|void|sv_catpvs_mg|SV* sv|const char* s
-Like C<sv_catpvn_mg>, but takes a C<NUL>-terminated literal string instead of a
+=for apidoc Am|void|sv_catpvs_mg|SV* sv|"literal string"
+Like C<sv_catpvn_mg>, but takes a literal string instead of a
string/length pair.
-=for apidoc Am|void|sv_setpvs|SV* sv|const char* s
-Like C<sv_setpvn>, but takes a C<NUL>-terminated literal string instead of a
+=for apidoc Am|void|sv_setpvs|SV* sv|"literal string"
+Like C<sv_setpvn>, but takes a literal string instead of a
string/length pair.
-=for apidoc Am|void|sv_setpvs_mg|SV* sv|const char* s
-Like C<sv_setpvn_mg>, but takes a C<NUL>-terminated literal string instead of a
+=for apidoc Am|void|sv_setpvs_mg|SV* sv|"literal string"
+Like C<sv_setpvn_mg>, but takes a literal string instead of a
string/length pair.
-=for apidoc Am|SV *|sv_setref_pvs|const char* s
-Like C<sv_setref_pvn>, but takes a C<NUL>-terminated literal string instead of
+=for apidoc Am|SV *|sv_setref_pvs|SV *const rv|const char *const classname|"literal string"
+Like C<sv_setref_pvn>, but takes a literal string instead of
a string/length pair.
=head1 Memory Management
-=for apidoc Ama|char*|savepvs|const char* s
-Like C<savepvn>, but takes a C<NUL>-terminated literal string instead of a
+=for apidoc Ama|char*|savepvs|"literal string"
+Like C<savepvn>, but takes a literal string instead of a
string/length pair.
-=for apidoc Ama|char*|savesharedpvs|const char* s
+=for apidoc Ama|char*|savesharedpvs|"literal string"
A version of C<savepvs()> which allocates the duplicate string in memory
which is shared between threads.
=head1 GV Functions
-=for apidoc Am|HV*|gv_stashpvs|const char* name|I32 create
-Like C<gv_stashpvn>, but takes a C<NUL>-terminated literal string instead of a
+=for apidoc Am|HV*|gv_stashpvs|"name"|I32 create
+Like C<gv_stashpvn>, but takes a literal string instead of a
string/length pair.
=head1 Hash Manipulation Functions
-=for apidoc Am|SV**|hv_fetchs|HV* tb|const char* key|I32 lval
-Like C<hv_fetch>, but takes a C<NUL>-terminated literal string instead of a
+=for apidoc Am|SV**|hv_fetchs|HV* tb|"key"|I32 lval
+Like C<hv_fetch>, but takes a literal string instead of a
string/length pair.
-=for apidoc Am|SV**|hv_stores|HV* tb|const char* key|NULLOK SV* val
-Like C<hv_store>, but takes a C<NUL>-terminated literal string instead of a
+=for apidoc Am|SV**|hv_stores|HV* tb|"key"|SV* val
+Like C<hv_store>, but takes a literal string instead of a
string/length pair
and omits the hash parameter.
=head1 Lexer interface
-=for apidoc Amx|void|lex_stuff_pvs|const char *pv|U32 flags
+=for apidoc Amx|void|lex_stuff_pvs|"pv"|U32 flags
-Like L</lex_stuff_pvn>, but takes a C<NUL>-terminated literal string instead of
+Like L</lex_stuff_pvn>, but takes a literal string instead of
a string/length pair.
=cut
*/
-/* concatenating with "" ensures that only literal strings are accepted as
- * argument */
-#define STR_WITH_LEN(s) ("" s ""), (sizeof(s)-1)
+/*
+=head1 Handy Values
-/* note that STR_WITH_LEN() can't be used as argument to macros or functions
- * that under some configurations might be macros, which means that it requires
- * the full Perl_xxx(aTHX_ ...) form for any API calls where it's used.
- */
+=for apidoc Amu|pair|STR_WITH_LEN|"literal string"
+
+Returns two comma separated tokens of the input literal string, and its length.
+This is convenience macro which helps out in some API calls.
+Note that it can't be used as an argument to macros or functions that under
+some configurations might be macros, which means that it requires the full
+Perl_xxx(aTHX_ ...) form for any API calls where it's used.
+
+=cut
+*/
+
+
+#define STR_WITH_LEN(s) ("" s ""), (sizeof(s)-1)
/* STR_WITH_LEN() shortcuts */
#define newSVpvs(str) Perl_newSVpvn(aTHX_ STR_WITH_LEN(str))
are equal. The C<len> parameter indicates the number of bytes to compare.
Returns zero if equal, or non-zero if non-equal.
+=for apidoc Am|bool|memEQs|char* s1|STRLEN l1|"s2"
+Like L</memEQ>, but the second string is a literal enclosed in double quotes,
+C<l1> gives the number of bytes in C<s1>.
+Returns zero if equal, or non-zero if non-equal.
+
=for apidoc Am|bool|memNE|char* s1|char* s2|STRLEN len
Test two buffers (which may contain embedded C<NUL> characters, to see if they
are not equal. The C<len> parameter indicates the number of bytes to compare.
Returns zero if non-equal, or non-zero if equal.
+=for apidoc Am|bool|memNEs|char* s1|STRLEN l1|"s2"
+Like L</memNE>, but the second string is a literal enclosed in double quotes,
+C<l1> gives the number of bytes in C<s1>.
+Returns zero if non-equal, or zero if non-equal.
+
=cut
+
+New macros should use the following conventions for their names (which are
+based on the underlying C library functions):
+
+ (mem | str n? ) (EQ | NE | LT | GT | GE | (( BEGIN | END ) P? )) l? s?
+
+ Each has two main parameters, string-like operands that are compared
+ against each other, as specified by the macro name. Some macros may
+ additionally have one or potentially even two length parameters. If a length
+ parameter applies to both string parameters, it will be positioned third;
+ otherwise any length parameter immediately follows the string parameter it
+ applies to.
+
+ If the prefix to the name is 'str', the string parameter is a pointer to a C
+ language string. Such a string does not contain embedded NUL bytes; its
+ length may be unknown, but can be calculated by C<strlen()>, since it is
+ terminated by a NUL, which isn't included in its length.
+
+ The optional 'n' following 'str' means that that there is a third parameter,
+ giving the maximum number of bytes to look at in each string. Even if both
+ strings are longer than the length parameter, those extra bytes will be
+ unexamined.
+
+ The 's' suffix means that the 2nd byte string parameter is a literal C
+ double-quoted string. Its length will automatically be calculated by the
+ macro, so no length parameter will ever be needed for it.
+
+ If the prefix is 'mem', the string parameters don't have to be C strings;
+ they may contain embedded NUL bytes, do not necessarily have a terminating
+ NUL, and their lengths can be known only through other means, which in
+ practice are additional parameter(s) passed to the function. All 'mem'
+ functions have at least one length parameter. Barring any 'l' or 's' suffix,
+ there is a single length parameter, in position 3, which applies to both
+ string parameters. The 's' suffix means, as described above, that the 2nd
+ string is a literal double-quoted C string (hence its length is calculated by
+ the macro, and the length parameter to the function applies just to the first
+ string parameter, and hence is positioned just after it). An 'l' suffix
+ means that the 2nd string parameter has its own length parameter, and the
+ signature will look like memFOOl(s1, l1, s2, l2).
+
+ BEGIN (and END) are for testing if the 2nd string is an initial (or final)
+ substring of the 1st string. 'P' if present indicates that the substring
+ must be a "proper" one in tha mathematical sense that the first one must be
+ strictly larger than the 2nd.
+
*/
-#define strNE(s1,s2) (strcmp(s1,s2))
-#define strEQ(s1,s2) (!strcmp(s1,s2))
+#define strNE(s1,s2) (strcmp(s1,s2) != 0)
+#define strEQ(s1,s2) (strcmp(s1,s2) == 0)
#define strLT(s1,s2) (strcmp(s1,s2) < 0)
#define strLE(s1,s2) (strcmp(s1,s2) <= 0)
#define strGT(s1,s2) (strcmp(s1,s2) > 0)
#define strGE(s1,s2) (strcmp(s1,s2) >= 0)
-#define strnNE(s1,s2,l) (strncmp(s1,s2,l))
-#define strnEQ(s1,s2,l) (!strncmp(s1,s2,l))
+#define strnNE(s1,s2,l) (strncmp(s1,s2,l) != 0)
+#define strnEQ(s1,s2,l) (strncmp(s1,s2,l) == 0)
-/* These names are controversial, so guarding against their being used in more
- * places than they already are. strBEGs and StrStartsWith are potential
- * candidates */
-#if defined(PERL_IN_DOIO_C) || defined(PERL_IN_GV_C) || defined(PERL_IN_HV_C) || defined(PERL_IN_LOCALE_C) || defined(PERL_IN_PERL_C) || defined(PERL_IN_TOKE_C) || defined(PERL_EXT)
-#define strNEs(s1,s2) (strncmp(s1,"" s2 "", sizeof(s2)-1))
-#define strEQs(s1,s2) (!strncmp(s1,"" s2 "", sizeof(s2)-1))
-#endif
-
-#define memNE(s1,s2,l) (memcmp(s1,s2,l))
-#define memEQ(s1,s2,l) (!memcmp(s1,s2,l))
+#define memEQ(s1,s2,l) (memcmp(((const void *) (s1)), ((const void *) (s2)), l) == 0)
+#define memNE(s1,s2,l) (! memEQ(s1,s2,l))
/* memEQ and memNE where second comparand is a string constant */
#define memEQs(s1, l, s2) \
(((sizeof(s2)-1) == (l)) && memEQ((s1), ("" s2 ""), (sizeof(s2)-1)))
#define memNEs(s1, l, s2) (! memEQs(s1, l, s2))
-/* memEQ and memNE where second comparand is a string constant
- * and we can assume the length of s1 is at least that of the string */
-#define _memEQs(s1, s2) \
- (memEQ((s1), ("" s2 ""), (sizeof(s2)-1)))
-#define _memNEs(s1, s2) (memNE((s1),("" s2 ""),(sizeof(s2)-1)))
+/* Keep these private until we decide it was a good idea */
+#if defined(PERL_CORE) || defined(PERL_EXT) || defined(PERL_EXT_POSIX)
+
+#define strBEGINs(s1,s2) (strncmp(s1,"" s2 "", sizeof(s2)-1) == 0)
+
+#define memBEGINs(s1, l, s2) \
+ ( (Ptrdiff_t) (l) >= (Ptrdiff_t) sizeof(s2) - 1 \
+ && memEQ(s1, "" s2 "", sizeof(s2)-1))
+#define memBEGINPs(s1, l, s2) \
+ ( (Ptrdiff_t) (l) > (Ptrdiff_t) sizeof(s2) - 1 \
+ && memEQ(s1, "" s2 "", sizeof(s2)-1))
+#define memENDs(s1, l, s2) \
+ ( (Ptrdiff_t) (l) >= (Ptrdiff_t) sizeof(s2) - 1 \
+ && memEQ(s1 + (l) - (sizeof(s2) - 1), "" s2 "", sizeof(s2)-1))
+#define memENDPs(s1, l, s2) \
+ ( (Ptrdiff_t) (l) > (Ptrdiff_t) sizeof(s2) \
+ && memEQ(s1 + (l) - (sizeof(s2) - 1), "" s2 "", sizeof(s2)-1))
+#endif /* End of making macros private */
#define memLT(s1,s2,l) (memcmp(s1,s2,l) < 0)
#define memLE(s1,s2,l) (memcmp(s1,s2,l) <= 0)
ones valid for it.) None are affected by C<use bytes>, and only the ones
with C<LC> in the name are affected by the current locale.
-The base function, e.g., C<isALPHA()>, takes an octet (either a C<char> or a
-C<U8>) as input and returns a boolean as to whether or not the character
-represented by that octet is (or on non-ASCII platforms, corresponds to) an
+The base function, e.g., C<isALPHA()>, takes any signed or unsigned value,
+treating it as a code point, and returns a boolean as to whether or not the
+character represented by it is (or on non-ASCII platforms, corresponds to) an
ASCII character in the named class based on platform, Unicode, and Perl rules.
If the input is a number that doesn't fit in an octet, FALSE is returned.
as if they are Latin-1 characters. For example, C<isWORDCHAR_L1()> will return
true when called with the code point 0xDF, which is a word character in both
ASCII and EBCDIC (though it represents different characters in each).
+If the input is a number that doesn't fit in an octet, FALSE is returned.
+(Perl's documentation uses a colloquial definition of Latin-1, to include all
+code points below 256.)
-Variant C<isI<FOO>_uvchr> is like the C<isI<FOO>_L1> variant, but accepts any UV code
-point as input. If the code point is larger than 255, Unicode rules are used
-to determine if it is in the character class. For example,
+Variant C<isI<FOO>_uvchr> is exactly like the C<isI<FOO>_L1> variant, for
+inputs below 256, but if the code point is larger than 255, Unicode rules are
+used to determine if it is in the character class. For example,
C<isWORDCHAR_uvchr(0x100)> returns TRUE, since 0x100 is LATIN CAPITAL LETTER A
WITH MACRON in Unicode, and is a word character.
Variant C<isI<FOO>_utf8_safe> is like C<isI<FOO>_uvchr>, but is used for UTF-8
-encoded strings. Each call classifies one character, even if the string
-contains many. This variant takes two parameters. The first, C<p>, is a
+encoded strings. Each call classifies the first character of the string. This
+variant takes two parameters. The first, C<p>, is a
pointer to the first byte of the character to be classified. (Recall that it
may take more than one byte to represent a character in UTF-8 strings.) The
second parameter, C<e>, points to anywhere in the string beyond the first
Variant C<isI<FOO>_utf8> is like C<isI<FOO>_utf8_safe>, but takes just a single
parameter, C<p>, which has the same meaning as the corresponding parameter does
in C<isI<FOO>_utf8_safe>. The function therefore can't check if it is reading
-beyond the end of the string. Starting in Perl v5.30, it will take a second
+beyond the end of the string. Starting in Perl v5.32, it will take a second
parameter, becoming a synonym for C<isI<FOO>_utf8_safe>. At that time every
program that uses it will have to be changed to successfully compile. In the
meantime, the first runtime call to C<isI<FOO>_utf8> from each call point in the
program will raise a deprecation warning, enabled by default. You can convert
your program now to use C<isI<FOO>_utf8_safe>, and avoid the warnings, and get an
-extra measure of protection, or you can wait until v5.30, when you'll be forced
+extra measure of protection, or you can wait until v5.32, when you'll be forced
to add the C<e> parameter.
-Variant C<isI<FOO>_LC> is like the C<isI<FOO>_A> and C<isI<FOO>_L1> variants, but the
-result is based on the current locale, which is what C<LC> in the name stands
-for. If Perl can determine that the current locale is a UTF-8 locale, it uses
-the published Unicode rules; otherwise, it uses the C library function that
-gives the named classification. For example, C<isDIGIT_LC()> when not in a
-UTF-8 locale returns the result of calling C<isdigit()>. FALSE is always
+Variant C<isI<FOO>_LC> is like the C<isI<FOO>_A> and C<isI<FOO>_L1> variants,
+but the result is based on the current locale, which is what C<LC> in the name
+stands for. If Perl can determine that the current locale is a UTF-8 locale,
+it uses the published Unicode rules; otherwise, it uses the C library function
+that gives the named classification. For example, C<isDIGIT_LC()> when not in
+a UTF-8 locale returns the result of calling C<isdigit()>. FALSE is always
returned if the input won't fit into an octet. On some platforms where the C
library function is known to be defective, Perl changes its result to follow
the POSIX standard's rules.
-Variant C<isI<FOO>_LC_uvchr> is like C<isI<FOO>_LC>, but is defined on any UV. It
-returns the same as C<isI<FOO>_LC> for input code points less than 256, and
-returns the hard-coded, not-affected-by-locale, Unicode results for larger ones.
+Variant C<isI<FOO>_LC_uvchr> acts exactly like C<isI<FOO>_LC> for inputs less
+than 256, but for larger ones it returns the Unicode classification of the code
+point.
Variant C<isI<FOO>_LC_utf8_safe> is like C<isI<FOO>_LC_uvchr>, but is used for UTF-8
-encoded strings. Each call classifies one character, even if the string
-contains many. This variant takes two parameters. The first, C<p>, is a
-pointer to the first byte of the character to be classified. (Recall that it
-may take more than one byte to represent a character in UTF-8 strings.) The
-second parameter, C<e>, points to anywhere in the string beyond the first
-character, up to one byte past the end of the entire string. The suffix
-C<_safe> in the function's name indicates that 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 FALSE, at the discretion of the implementation, and subject to change in
-future releases.
+encoded strings. Each call classifies the first character of the string. This
+variant takes two parameters. The first, C<p>, is a pointer to the first byte
+of the character to be classified. (Recall that it may take more than one byte
+to represent a character in UTF-8 strings.) The second parameter, C<e>,
+points to anywhere in the string beyond the first character, up to one byte
+past the end of the entire string. The suffix C<_safe> in the function's name
+indicates that 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 FALSE, at the discretion of the
+implementation, and subject to change in future releases.
Variant C<isI<FOO>_LC_utf8> is like C<isI<FOO>_LC_utf8_safe>, but takes just a single
parameter, C<p>, which has the same meaning as the corresponding parameter does
in C<isI<FOO>_LC_utf8_safe>. The function therefore can't check if it is reading
-beyond the end of the string. Starting in Perl v5.30, it will take a second
+beyond the end of the string. Starting in Perl v5.32, it will take a second
parameter, becoming a synonym for C<isI<FOO>_LC_utf8_safe>. At that time every
program that uses it will have to be changed to successfully compile. In the
meantime, the first runtime call to C<isI<FOO>_LC_utf8> from each call point in
the program will raise a deprecation warning, enabled by default. You can
convert your program now to use C<isI<FOO>_LC_utf8_safe>, and avoid the warnings,
-and get an extra measure of protection, or you can wait until v5.30, when
+and get an extra measure of protection, or you can wait until v5.32, when
you'll be forced to add the C<e> parameter.
-=for apidoc Am|bool|isALPHA|char ch
-Returns a boolean indicating whether the specified character is an
-alphabetic character, analogous to C<m/[[:alpha:]]/>.
+=for apidoc Am|bool|isALPHA|int ch
+Returns a boolean indicating whether the specified input is one of C<[A-Za-z]>,
+analogous to C<m/[[:alpha:]]/>.
See the L<top of this section|/Character classification> for an explanation of
variants
C<isALPHA_A>, C<isALPHA_L1>, C<isALPHA_uvchr>, C<isALPHA_utf8_safe>,
C<isALPHA_LC>, C<isALPHA_LC_uvchr>, and C<isALPHA_LC_utf8_safe>.
-=for apidoc Am|bool|isALPHANUMERIC|char ch
-Returns a boolean indicating whether the specified character is a either an
-alphabetic character or decimal digit, analogous to C<m/[[:alnum:]]/>.
+=cut
+
+Here and below, we add the protoypes of these macros for downstream programs
+that would be interested in them, such as Devel::PPPort
+
+=for apidoc Amh|bool|isALPHA_A|int ch
+=for apidoc Amh|bool|isALPHA_L1|int ch
+=for apidoc Amh|bool|isALPHA_uvchr|int ch
+=for apidoc Amh|bool|isALPHA_utf8_safe|U8 * s|U8 * end
+=for apidoc Amh|bool|isALPHA_utf8|U8 * s
+=for apidoc Amh|bool|isALPHA_LC|int ch
+=for apidoc Amh|bool|isALPHA_LC_uvchr|int ch
+=for apidoc Amh|bool|isALPHA_LC_utf8_safe|U8 * s| U8 *end
+
+=for apidoc Am|bool|isALPHANUMERIC|int 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
variants
C<isALPHANUMERIC_A>, C<isALPHANUMERIC_L1>, C<isALPHANUMERIC_uvchr>,
C<isALPHANUMERIC_utf8_safe>, C<isALPHANUMERIC_LC>, C<isALPHANUMERIC_LC_uvchr>,
and C<isALPHANUMERIC_LC_utf8_safe>.
-=for apidoc Am|bool|isASCII|char ch
+A (discouraged from use) synonym is C<isALNUMC> (where the C<C> suffix means
+this corresponds to the C language alphanumeric definition). Also
+there are the variants
+C<isALNUMC_A>, C<isALNUMC_L1>
+C<isALNUMC_LC>, and C<isALNUMC_LC_uvchr>.
+
+=for apidoc Amh|bool|isALPHANUMERIC_A|int ch
+=for apidoc Amh|bool|isALPHANUMERIC_L1|int ch
+=for apidoc Amh|bool|isALPHANUMERIC_uvchr|int ch
+=for apidoc Amh|bool|isALPHANUMERIC_utf8_safe|U8 * s|U8 * end
+=for apidoc Amh|bool|isALPHANUMERIC_utf8|U8 * s
+=for apidoc Amh|bool|isALPHANUMERIC_LC|int ch
+=for apidoc Amh|bool|isALPHANUMERIC_LC_uvchr|int ch
+=for apidoc Amh|bool|isALPHANUMERIC_LC_utf8_safe|U8 * s| U8 *end
+=for apidoc Amh|bool|isALNUMC|int ch
+=for apidoc Amh|bool|isALNUMC_A|int ch
+=for apidoc Amh|bool|isALNUMC_L1|int ch
+=for apidoc Amh|bool|isALNUMC_LC|int ch
+=for apidoc Amh|bool|isALNUMC_LC_uvchr|int ch
+
+=for apidoc Am|bool|isASCII|int ch
Returns a boolean indicating whether the specified character is one of the 128
characters in the ASCII character set, analogous to C<m/[[:ascii:]]/>.
On non-ASCII platforms, it returns TRUE iff this
library routine C<isascii()>. In these cases, the variants whose names contain
C<LC> are the same as the corresponding ones without.
+=for apidoc Amh|bool|isASCII_A|int ch
+=for apidoc Amh|bool|isASCII_L1|int ch
+=for apidoc Amh|bool|isASCII_uvchr|int ch
+=for apidoc Amh|bool|isASCII_utf8_safe|U8 * s|U8 * end
+=for apidoc Amh|bool|isASCII_utf8|U8 * s
+=for apidoc Amh|bool|isASCII_LC|int ch
+=for apidoc Amh|bool|isASCII_LC_uvchr|int ch
+=for apidoc Amh|bool|isASCII_LC_utf8_safe|U8 * s| U8 *end
+
Also note, that because all ASCII characters are UTF-8 invariant (meaning they
have the exact same representation (always a single byte) whether encoded in
UTF-8 or not), C<isASCII> will give the correct results when called with any
C<isblank()>. In these cases, the variants whose names contain C<LC> are
the same as the corresponding ones without.
+=for apidoc Amh|bool|isBLANK_A|int ch
+=for apidoc Amh|bool|isBLANK_L1|int ch
+=for apidoc Amh|bool|isBLANK_uvchr|int ch
+=for apidoc Amh|bool|isBLANK_utf8_safe|U8 * s|U8 * end
+=for apidoc Amh|bool|isBLANK_utf8|U8 * s
+=for apidoc Amh|bool|isBLANK_LC|int ch
+=for apidoc Amh|bool|isBLANK_LC_uvchr|int ch
+=for apidoc Amh|bool|isBLANK_LC_utf8_safe|U8 * s| U8 *end
+
=for apidoc Am|bool|isCNTRL|char ch
Returns a boolean indicating whether the specified character is a
control character, analogous to C<m/[[:cntrl:]]/>.
C<isCNTRL_LC>, C<isCNTRL_LC_uvchr>, and C<isCNTRL_LC_utf8_safe> On EBCDIC
platforms, you almost always want to use the C<isCNTRL_L1> variant.
+=for apidoc Amh|bool|isCNTRL_A|int ch
+=for apidoc Amh|bool|isCNTRL_L1|int ch
+=for apidoc Amh|bool|isCNTRL_uvchr|int ch
+=for apidoc Amh|bool|isCNTRL_utf8_safe|U8 * s|U8 * end
+=for apidoc Amh|bool|isCNTRL_utf8|U8 * s
+=for apidoc Amh|bool|isCNTRL_LC|int ch
+=for apidoc Amh|bool|isCNTRL_LC_uvchr|int ch
+=for apidoc Amh|bool|isCNTRL_LC_utf8_safe|U8 * s| U8 *end
+
=for apidoc Am|bool|isDIGIT|char ch
Returns a boolean indicating whether the specified character is a
digit, analogous to C<m/[[:digit:]]/>.
C<isDIGIT_uvchr>, C<isDIGIT_utf8_safe>, C<isDIGIT_LC>, C<isDIGIT_LC_uvchr>, and
C<isDIGIT_LC_utf8_safe>.
+=for apidoc Amh|bool|isDIGIT_A|int ch
+=for apidoc Amh|bool|isDIGIT_L1|int ch
+=for apidoc Amh|bool|isDIGIT_uvchr|int ch
+=for apidoc Amh|bool|isDIGIT_utf8_safe|U8 * s|U8 * end
+=for apidoc Amh|bool|isDIGIT_utf8|U8 * s
+=for apidoc Amh|bool|isDIGIT_LC|int ch
+=for apidoc Amh|bool|isDIGIT_LC_uvchr|int ch
+=for apidoc Amh|bool|isDIGIT_LC_utf8_safe|U8 * s| U8 *end
+
=for apidoc Am|bool|isGRAPH|char ch
Returns a boolean indicating whether the specified character is a
graphic character, analogous to C<m/[[:graph:]]/>.
variants C<isGRAPH_A>, C<isGRAPH_L1>, C<isGRAPH_uvchr>, C<isGRAPH_utf8_safe>,
C<isGRAPH_LC>, C<isGRAPH_LC_uvchr>, and C<isGRAPH_LC_utf8_safe>.
+=for apidoc Amh|bool|isGRAPH_A|int ch
+=for apidoc Amh|bool|isGRAPH_L1|int ch
+=for apidoc Amh|bool|isGRAPH_uvchr|int ch
+=for apidoc Amh|bool|isGRAPH_utf8_safe|U8 * s|U8 * end
+=for apidoc Amh|bool|isGRAPH_utf8|U8 * s
+=for apidoc Amh|bool|isGRAPH_LC|int ch
+=for apidoc Amh|bool|isGRAPH_LC_uvchr|int ch
+=for apidoc Amh|bool|isGRAPH_LC_utf8_safe|U8 * s| U8 *end
+
=for apidoc Am|bool|isLOWER|char ch
Returns a boolean indicating whether the specified character is a
lowercase character, analogous to C<m/[[:lower:]]/>.
C<isLOWER_A>, C<isLOWER_L1>, C<isLOWER_uvchr>, C<isLOWER_utf8_safe>,
C<isLOWER_LC>, C<isLOWER_LC_uvchr>, and C<isLOWER_LC_utf8_safe>.
+=for apidoc Amh|bool|isLOWER_A|int ch
+=for apidoc Amh|bool|isLOWER_L1|int ch
+=for apidoc Amh|bool|isLOWER_uvchr|int ch
+=for apidoc Amh|bool|isLOWER_utf8_safe|U8 * s|U8 * end
+=for apidoc Amh|bool|isLOWER_utf8|U8 * s
+=for apidoc Amh|bool|isLOWER_LC|int ch
+=for apidoc Amh|bool|isLOWER_LC_uvchr|int ch
+=for apidoc Amh|bool|isLOWER_LC_utf8_safe|U8 * s| U8 *end
+
=for apidoc Am|bool|isOCTAL|char 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 Amh|bool|isOCTAL_A|int ch
+=for apidoc Amh|bool|isOCTAL_L1|int ch
+
=for apidoc Am|bool|isPUNCT|char ch
Returns a boolean indicating whether the specified character is a
punctuation character, analogous to C<m/[[:punct:]]/>.
variants C<isPUNCT_A>, C<isPUNCT_L1>, C<isPUNCT_uvchr>, C<isPUNCT_utf8_safe>,
C<isPUNCT_LC>, C<isPUNCT_LC_uvchr>, and C<isPUNCT_LC_utf8_safe>.
+=for apidoc Amh|bool|isPUNCT_A|int ch
+=for apidoc Amh|bool|isPUNCT_L1|int ch
+=for apidoc Amh|bool|isPUNCT_uvchr|int ch
+=for apidoc Amh|bool|isPUNCT_utf8_safe|U8 * s|U8 * end
+=for apidoc Amh|bool|isPUNCT_utf8|U8 * s
+=for apidoc Amh|bool|isPUNCT_LC|int ch
+=for apidoc Amh|bool|isPUNCT_LC_uvchr|int ch
+=for apidoc Amh|bool|isPUNCT_LC_utf8_safe|U8 * s| U8 *end
+
=for apidoc Am|bool|isSPACE|char ch
Returns a boolean indicating whether the specified character is a
whitespace character. This is analogous
C<isSPACE_A>, C<isSPACE_L1>, C<isSPACE_uvchr>, C<isSPACE_utf8_safe>,
C<isSPACE_LC>, C<isSPACE_LC_uvchr>, and C<isSPACE_LC_utf8_safe>.
+=for apidoc Amh|bool|isSPACE_A|int ch
+=for apidoc Amh|bool|isSPACE_L1|int ch
+=for apidoc Amh|bool|isSPACE_uvchr|int ch
+=for apidoc Amh|bool|isSPACE_utf8_safe|U8 * s|U8 * end
+=for apidoc Amh|bool|isSPACE_utf8|U8 * s
+=for apidoc Amh|bool|isSPACE_LC|int ch
+=for apidoc Amh|bool|isSPACE_LC_uvchr|int ch
+=for apidoc Amh|bool|isSPACE_LC_utf8_safe|U8 * s| U8 *end
+
=for apidoc Am|bool|isPSXSPC|char ch
(short for Posix Space)
Starting in 5.18, this is identical in all its forms to the
variants C<isPSXSPC_A>, C<isPSXSPC_L1>, C<isPSXSPC_uvchr>, C<isPSXSPC_utf8_safe>,
C<isPSXSPC_LC>, C<isPSXSPC_LC_uvchr>, and C<isPSXSPC_LC_utf8_safe>.
+=for apidoc Amh|bool|isPSXSPC_A|int ch
+=for apidoc Amh|bool|isPSXSPC_L1|int ch
+=for apidoc Amh|bool|isPSXSPC_uvchr|int ch
+=for apidoc Amh|bool|isPSXSPC_utf8_safe|U8 * s|U8 * end
+=for apidoc Amh|bool|isPSXSPC_utf8|U8 * s
+=for apidoc Amh|bool|isPSXSPC_LC|int ch
+=for apidoc Amh|bool|isPSXSPC_LC_uvchr|int ch
+=for apidoc Amh|bool|isPSXSPC_LC_utf8_safe|U8 * s| U8 *end
+
=for apidoc Am|bool|isUPPER|char ch
Returns a boolean indicating whether the specified character is an
uppercase character, analogous to C<m/[[:upper:]]/>.
variants C<isUPPER_A>, C<isUPPER_L1>, C<isUPPER_uvchr>, C<isUPPER_utf8_safe>,
C<isUPPER_LC>, C<isUPPER_LC_uvchr>, and C<isUPPER_LC_utf8_safe>.
+=for apidoc Amh|bool|isUPPER_A|int ch
+=for apidoc Amh|bool|isUPPER_L1|int ch
+=for apidoc Amh|bool|isUPPER_uvchr|int ch
+=for apidoc Amh|bool|isUPPER_utf8_safe|U8 * s|U8 * end
+=for apidoc Amh|bool|isUPPER_utf8|U8 * s
+=for apidoc Amh|bool|isUPPER_LC|int ch
+=for apidoc Amh|bool|isUPPER_LC_uvchr|int ch
+=for apidoc Amh|bool|isUPPER_LC_utf8_safe|U8 * s| U8 *end
+
=for apidoc Am|bool|isPRINT|char ch
Returns a boolean indicating whether the specified character is a
printable character, analogous to C<m/[[:print:]]/>.
C<isPRINT_A>, C<isPRINT_L1>, C<isPRINT_uvchr>, C<isPRINT_utf8_safe>,
C<isPRINT_LC>, C<isPRINT_LC_uvchr>, and C<isPRINT_LC_utf8_safe>.
+=for apidoc Amh|bool|isPRINT_A|int ch
+=for apidoc Amh|bool|isPRINT_L1|int ch
+=for apidoc Amh|bool|isPRINT_uvchr|int ch
+=for apidoc Amh|bool|isPRINT_utf8_safe|U8 * s|U8 * end
+=for apidoc Amh|bool|isPRINT_utf8|U8 * s
+=for apidoc Amh|bool|isPRINT_LC|int ch
+=for apidoc Amh|bool|isPRINT_LC_uvchr|int ch
+=for apidoc Amh|bool|isPRINT_LC_utf8_safe|U8 * s| U8 *end
+
=for apidoc Am|bool|isWORDCHAR|char 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
C<isWORDCHAR_LC_utf8_safe> are also as described there, but additionally
include the platform's native underscore.
+=for apidoc Amh|bool|isWORDCHAR_A|int ch
+=for apidoc Amh|bool|isWORDCHAR_L1|int ch
+=for apidoc Amh|bool|isWORDCHAR_uvchr|int ch
+=for apidoc Amh|bool|isWORDCHAR_utf8_safe|U8 * s|U8 * end
+=for apidoc Amh|bool|isWORDCHAR_utf8|U8 * s
+=for apidoc Amh|bool|isWORDCHAR_LC|int ch
+=for apidoc Amh|bool|isWORDCHAR_LC_uvchr|int ch
+=for apidoc Amh|bool|isWORDCHAR_LC_utf8_safe|U8 * s| U8 *end
+=for apidoc Amh|bool|isALNUM|int ch
+=for apidoc Amh|bool|isALNUM_A|int ch
+=for apidoc Amh|bool|isALNUM_LC|int ch
+=for apidoc Amh|bool|isALNUM_LC_uvchr|int ch
+
=for apidoc Am|bool|isXDIGIT|char ch
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()>
C<isXDIGIT_uvchr>, C<isXDIGIT_utf8_safe>, C<isXDIGIT_LC>, C<isXDIGIT_LC_uvchr>,
and C<isXDIGIT_LC_utf8_safe>.
+=for apidoc Amh|bool|isXDIGIT_A|int ch
+=for apidoc Amh|bool|isXDIGIT_L1|int ch
+=for apidoc Amh|bool|isXDIGIT_uvchr|int ch
+=for apidoc Amh|bool|isXDIGIT_utf8_safe|U8 * s|U8 * end
+=for apidoc Amh|bool|isXDIGIT_utf8|U8 * s
+=for apidoc Amh|bool|isXDIGIT_LC|int ch
+=for apidoc Amh|bool|isXDIGIT_LC_uvchr|int ch
+=for apidoc Amh|bool|isXDIGIT_LC_utf8_safe|U8 * s| U8 *end
+
=for apidoc Am|bool|isIDFIRST|char ch
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
C<isIDFIRST_A>, C<isIDFIRST_L1>, C<isIDFIRST_uvchr>, C<isIDFIRST_utf8_safe>,
C<isIDFIRST_LC>, C<isIDFIRST_LC_uvchr>, and C<isIDFIRST_LC_utf8_safe>.
+=for apidoc Amh|bool|isIDFIRST_A|int ch
+=for apidoc Amh|bool|isIDFIRST_L1|int ch
+=for apidoc Amh|bool|isIDFIRST_uvchr|int ch
+=for apidoc Amh|bool|isIDFIRST_utf8_safe|U8 * s|U8 * end
+=for apidoc Amh|bool|isIDFIRST_utf8|U8 * s
+=for apidoc Amh|bool|isIDFIRST_LC|int ch
+=for apidoc Amh|bool|isIDFIRST_LC_uvchr|int ch
+=for apidoc Amh|bool|isIDFIRST_LC_utf8_safe|U8 * s| U8 *end
+
=for apidoc Am|bool|isIDCONT|char ch
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<isIDCONT_utf8_safe>, C<isIDCONT_LC>, C<isIDCONT_LC_uvchr>, and
C<isIDCONT_LC_utf8_safe>.
+=for apidoc Amh|bool|isIDCONT_A|int ch
+=for apidoc Amh|bool|isIDCONT_L1|int ch
+=for apidoc Amh|bool|isIDCONT_uvchr|int ch
+=for apidoc Amh|bool|isIDCONT_utf8_safe|U8 * s|U8 * end
+=for apidoc Amh|bool|isIDCONT_utf8|U8 * s
+=for apidoc Amh|bool|isIDCONT_LC|int ch
+=for apidoc Amh|bool|isIDCONT_LC_uvchr|int ch
+=for apidoc Amh|bool|isIDCONT_LC_utf8_safe|U8 * s| U8 *end
+
=head1 Miscellaneous Functions
=for apidoc Am|U8|READ_XDIGIT|char str*
no other function that is crippled by not being able to give the correct
results for the full range of possible inputs has been implemented here.
-=for apidoc Am|U8|toUPPER|U8 ch
+=for apidoc Am|U8|toUPPER|int ch
Converts the specified character to uppercase. If the input is anything but an
ASCII lowercase character, that input character itself is returned. Variant
C<toUPPER_A> is equivalent.
=for apidoc Am|UV|toUPPER_utf8|U8* p|U8* s|STRLEN* lenp
This is like C<L</toUPPER_utf8_safe>>, but doesn't have the C<e>
parameter The function therefore can't check if it is reading
-beyond the end of the string. Starting in Perl v5.30, it will take the C<e>
+beyond the end of the string. Starting in Perl v5.32, it will take the C<e>
parameter, becoming a synonym for C<toUPPER_utf8_safe>. At that time every
program that uses it will have to be changed to successfully compile. In the
meantime, the first runtime call to C<toUPPER_utf8> from each call point in the
program will raise a deprecation warning, enabled by default. You can convert
your program now to use C<toUPPER_utf8_safe>, and avoid the warnings, and get an
-extra measure of protection, or you can wait until v5.30, when you'll be forced
+extra measure of protection, or you can wait until v5.32, when you'll be forced
to add the C<e> parameter.
=for apidoc Am|U8|toFOLD|U8 ch
=for apidoc Am|UV|toFOLD_utf8|U8* p|U8* s|STRLEN* lenp
This is like C<L</toFOLD_utf8_safe>>, but doesn't have the C<e>
parameter The function therefore can't check if it is reading
-beyond the end of the string. Starting in Perl v5.30, it will take the C<e>
+beyond the end of the string. Starting in Perl v5.32, it will take the C<e>
parameter, becoming a synonym for C<toFOLD_utf8_safe>. At that time every
program that uses it will have to be changed to successfully compile. In the
meantime, the first runtime call to C<toFOLD_utf8> from each call point in the
program will raise a deprecation warning, enabled by default. You can convert
your program now to use C<toFOLD_utf8_safe>, and avoid the warnings, and get an
-extra measure of protection, or you can wait until v5.30, when you'll be forced
+extra measure of protection, or you can wait until v5.32, when you'll be forced
to add the C<e> parameter.
=for apidoc Am|U8|toLOWER|U8 ch
=for apidoc Am|UV|toLOWER_utf8|U8* p|U8* s|STRLEN* lenp
This is like C<L</toLOWER_utf8_safe>>, but doesn't have the C<e>
parameter The function therefore can't check if it is reading
-beyond the end of the string. Starting in Perl v5.30, it will take the C<e>
+beyond the end of the string. Starting in Perl v5.32, it will take the C<e>
parameter, becoming a synonym for C<toLOWER_utf8_safe>. At that time every
program that uses it will have to be changed to successfully compile. In the
meantime, the first runtime call to C<toLOWER_utf8> from each call point in the
program will raise a deprecation warning, enabled by default. You can convert
your program now to use C<toLOWER_utf8_safe>, and avoid the warnings, and get an
-extra measure of protection, or you can wait until v5.30, when you'll be forced
+extra measure of protection, or you can wait until v5.32, when you'll be forced
to add the C<e> parameter.
=for apidoc Am|U8|toTITLE|U8 ch
=for apidoc Am|UV|toTITLE_utf8|U8* p|U8* s|STRLEN* lenp
This is like C<L</toLOWER_utf8_safe>>, but doesn't have the C<e>
parameter The function therefore can't check if it is reading
-beyond the end of the string. Starting in Perl v5.30, it will take the C<e>
+beyond the end of the string. Starting in Perl v5.32, it will take the C<e>
parameter, becoming a synonym for C<toTITLE_utf8_safe>. At that time every
program that uses it will have to be changed to successfully compile. In the
meantime, the first runtime call to C<toTITLE_utf8> from each call point in the
program will raise a deprecation warning, enabled by default. You can convert
your program now to use C<toTITLE_utf8_safe>, and avoid the warnings, and get an
-extra measure of protection, or you can wait until v5.30, when you'll be forced
+extra measure of protection, or you can wait until v5.32, when you'll be forced
to add the C<e> parameter.
=cut
*/
-/* Specify the widest unsigned type on the platform. Use U64TYPE because U64
- * is known only in the perl core, and this macro can be called from outside
- * that */
-#ifdef HAS_QUAD
-# define WIDEST_UTYPE U64TYPE
+/*
+ void below because that's the best fit, and works for Devel::PPPort
+=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
+
+ WIDEST_UTYPE my_uv;
+
+or casts
+
+ my_uv = (WIDEST_UTYPE) val;
+
+=cut
+
+*/
+#ifdef QUADKIND
+# define WIDEST_UTYPE U64
#else
# define WIDEST_UTYPE U32
#endif
#define FITS_IN_8_BITS(c) (1)
#endif
+/* Returns true if l <= c <= l + n, where 'l' and 'n' are non-negative
+ * Written this way so that after optimization, only one conditional test is
+ * needed. */
+#define withinCOUNT(c, l, n) (__ASSERT_((l) >= 0) __ASSERT_((n) >= (0)) \
+ (((WIDEST_UTYPE) (((c) | 0) - ((l) | 0))) <= (((WIDEST_UTYPE) ((n) | 0)))))
+
+/* Returns true if c is in the range l..u, where 'l' is non-negative
+ * Written this way so that after optimization, only one conditional test is
+ * needed. */
+#define inRANGE(c, l, u) (__ASSERT_((l) >= 0) __ASSERT_((u) >= (l)) \
+ ( (sizeof(c) == sizeof(U8)) ? withinCOUNT(((U8) (c)), (l), ((u) - (l))) \
+ : (sizeof(c) == sizeof(U16)) ? withinCOUNT(((U16) (c)), (l), ((u) - (l))) \
+ : (sizeof(c) == sizeof(U32)) ? withinCOUNT(((U32) (c)), (l), ((u) - (l))) \
+ : (__ASSERT_(sizeof(c) == sizeof(WIDEST_UTYPE)) \
+ withinCOUNT(( (c)), (l), ((u) - (l))))))
+
#ifdef EBCDIC
# ifndef _ALL_SOURCE
/* The native libc isascii() et.al. functions return the wrong results
*
* The first group of these is ordered in what I (khw) estimate to be the
* frequency of their use. This gives a slight edge to exiting a loop earlier
- * (in reginclass() in regexec.c) */
+ * (in reginclass() in regexec.c). Except \v should be last, as it isn't a
+ * real Posix character class, and some (small) inefficiencies in regular
+ * expression handling would be introduced by putting it in the middle of those
+ * that are. Also, cntrl and ascii come after the others as it may be useful
+ * to group these which have no members that match above Latin1, (or above
+ * ASCII in the latter case) */
+
# define _CC_WORDCHAR 0 /* \w and [:word:] */
# define _CC_DIGIT 1 /* \d and [:digit:] */
# define _CC_ALPHA 2 /* [:alpha:] */
# define _CC_ALPHANUMERIC 7 /* [:alnum:] */
# define _CC_GRAPH 8 /* [:graph:] */
# define _CC_CASED 9 /* [:lower:] or [:upper:] under /i */
-
-#define _FIRST_NON_SWASH_CC 10
-/* The character classes above are implemented with swashes. The second group
- * (just below) contains the ones implemented without. These are also sorted
- * in rough order of the frequency of their use, except that \v should be last,
- * as it isn't a real Posix character class, and some (small) inefficiencies in
- * regular expression handling would be introduced by putting it in the middle
- * of those that are. Also, cntrl and ascii come after the others as it may be
- * useful to group these which have no members that match above Latin1, (or
- * above ASCII in the latter case) */
-
# define _CC_SPACE 10 /* \s, [:space:] */
# define _CC_PSXSPC _CC_SPACE /* XXX Temporary, can be removed
when the deprecated isFOO_utf8()
} _char_class_number;
#endif
-#define POSIX_SWASH_COUNT _FIRST_NON_SWASH_CC
#define POSIX_CC_COUNT (_HIGHEST_REGCOMP_DOT_H_SYNC + 1)
-#if defined(PERL_IN_UTF8_C) \
- || defined(PERL_IN_REGCOMP_C) \
- || defined(PERL_IN_REGEXEC_C)
-# if _CC_WORDCHAR != 0 || _CC_DIGIT != 1 || _CC_ALPHA != 2 || _CC_LOWER != 3 \
- || _CC_UPPER != 4 || _CC_PUNCT != 5 || _CC_PRINT != 6 \
- || _CC_ALPHANUMERIC != 7 || _CC_GRAPH != 8 || _CC_CASED != 9
- #error Need to adjust order of swash_property_names[]
-# endif
-
-/* This is declared static in each of the few files that this is #defined for
- * to keep them from being publicly accessible. Hence there is a small amount
- * of wasted space */
-
-static const char* const swash_property_names[] = {
- "XPosixWord",
- "XPosixDigit",
- "XPosixAlpha",
- "XPosixLower",
- "XPosixUpper",
- "XPosixPunct",
- "XPosixPrint",
- "XPosixAlnum",
- "XPosixGraph",
- "Cased"
-};
-#endif
-
START_EXTERN_C
# ifdef DOINIT
EXTCONST U32 PL_charclass[] = {
&& ((PL_charclass[(U8) (c)] & _CC_mask_A(classnum)) \
== _CC_mask_A(classnum)))
-# define isALPHA_A(c) _generic_isCC_A(c, _CC_ALPHA)
+/* On ASCII platforms certain classes form a single range. It's faster to
+ * special case these. isDIGIT is a single range on all platforms */
+# ifdef EBCDIC
+# define isALPHA_A(c) _generic_isCC_A(c, _CC_ALPHA)
+# define isGRAPH_A(c) _generic_isCC_A(c, _CC_GRAPH)
+# define isLOWER_A(c) _generic_isCC_A(c, _CC_LOWER)
+# define isPRINT_A(c) _generic_isCC_A(c, _CC_PRINT)
+# define isUPPER_A(c) _generic_isCC_A(c, _CC_UPPER)
+# else
+ /* By folding the upper and lowercase, we can use a single range */
+# define isALPHA_A(c) inRANGE((~('A' ^ 'a') & (c)), 'A', 'Z')
+# define isGRAPH_A(c) inRANGE(c, ' ' + 1, 0x7e)
+# define isLOWER_A(c) inRANGE(c, 'a', 'z')
+# define isPRINT_A(c) inRANGE(c, ' ', 0x7e)
+# define isUPPER_A(c) inRANGE(c, 'A', 'Z')
+# endif
# define isALPHANUMERIC_A(c) _generic_isCC_A(c, _CC_ALPHANUMERIC)
# define isBLANK_A(c) _generic_isCC_A(c, _CC_BLANK)
# define isCNTRL_A(c) _generic_isCC_A(c, _CC_CNTRL)
-# define isDIGIT_A(c) _generic_isCC(c, _CC_DIGIT) /* No non-ASCII digits */
-# define isGRAPH_A(c) _generic_isCC_A(c, _CC_GRAPH)
-# define isLOWER_A(c) _generic_isCC_A(c, _CC_LOWER)
-# define isPRINT_A(c) _generic_isCC_A(c, _CC_PRINT)
+# define isDIGIT_A(c) inRANGE(c, '0', '9')
# define isPUNCT_A(c) _generic_isCC_A(c, _CC_PUNCT)
# define isSPACE_A(c) _generic_isCC_A(c, _CC_SPACE)
-# define isUPPER_A(c) _generic_isCC_A(c, _CC_UPPER)
# define isWORDCHAR_A(c) _generic_isCC_A(c, _CC_WORDCHAR)
# define isXDIGIT_A(c) _generic_isCC(c, _CC_XDIGIT) /* No non-ASCII xdigits
*/
* hard-code various macro definitions that wouldn't otherwise be available
* to it. Most are coded based on first principles. These are written to
* avoid EBCDIC vs. ASCII #ifdef's as much as possible. */
-# define isDIGIT_A(c) ((c) <= '9' && (c) >= '0')
+# define isDIGIT_A(c) inRANGE(c, '0', '9')
# define isBLANK_A(c) ((c) == ' ' || (c) == '\t')
# define isSPACE_A(c) (isBLANK_A(c) \
|| (c) == '\n' \
* uppercase. The tests for those aren't necessary on ASCII, but hurt only
* performance (if optimization isn't on), and allow the same code to be
* used for both platform types */
-# define isLOWER_A(c) ((c) >= 'a' && (c) <= 'z' \
- && ( (c) <= 'i' \
- || ((c) >= 'j' && (c) <= 'r') \
- || (c) >= 's'))
-# define isUPPER_A(c) ((c) >= 'A' && (c) <= 'Z' \
- && ( (c) <= 'I' \
- || ((c) >= 'J' && (c) <= 'R') \
- || (c) >= 'S'))
+# define isLOWER_A(c) inRANGE((c), 'a', 'i') \
+ || inRANGE((c), 'j', 'r') \
+ || inRANGE((c), 's', 'z')
+# define isUPPER_A(c) inRANGE((c), 'A', 'I') \
+ || inRANGE((c), 'J', 'R') \
+ || inRANGE((c), 'S', 'Z')
# define isALPHA_A(c) (isUPPER_A(c) || isLOWER_A(c))
# define isALPHANUMERIC_A(c) (isALPHA_A(c) || isDIGIT_A(c))
# define isWORDCHAR_A(c) (isALPHANUMERIC_A(c) || (c) == '_')
# define isIDFIRST_A(c) (isALPHA_A(c) || (c) == '_')
-# define isXDIGIT_A(c) (isDIGIT_A(c) \
- || ((c) >= 'a' && (c) <= 'f') \
- || ((c) <= 'F' && (c) >= 'A'))
+# define isXDIGIT_A(c) ( isDIGIT_A(c) \
+ || inRANGE((c), 'a', 'f') \
+ || inRANGE((c), 'A', 'F')
# define isPUNCT_A(c) ((c) == '-' || (c) == '!' || (c) == '"' \
|| (c) == '#' || (c) == '$' || (c) == '%' \
|| (c) == '&' || (c) == '\'' || (c) == '(' \
# define isCNTRL_A(c) ((c) == '\0' || (c) == '\a' || (c) == '\b' \
|| (c) == '\f' || (c) == '\n' || (c) == '\r' \
|| (c) == '\t' || (c) == '\v' \
- || ((c) <= 3 && (c) >= 1) /* SOH, STX, ETX */ \
+ || inRANGE((c), 1, 3) /* SOH, STX, ETX */ \
|| (c) == 7 /* U+7F DEL */ \
- || ((c) <= 0x13 && (c) >= 0x0E) /* SO, SI */ \
- /* DLE, DC[1-3] */ \
+ || inRANGE((c), 0x0E, 0x13) /* SO SI DLE \
+ DC[1-3] */ \
|| (c) == 0x18 /* U+18 CAN */ \
|| (c) == 0x19 /* U+19 EOM */ \
- || ((c) <= 0x1F && (c) >= 0x1C) /* [FGRU]S */ \
+ || inRANGE((c), 0x1C, 0x1F) /* [FGRU]S */ \
|| (c) == 0x26 /* U+17 ETB */ \
|| (c) == 0x27 /* U+1B ESC */ \
|| (c) == 0x2D /* U+05 ENQ */ \
|| NATIVE_TO_LATIN1((U8) c) == 0xA0)))
# define isUPPER_L1(c) (isUPPER_A(c) \
|| (FITS_IN_8_BITS(c) \
- && ( NATIVE_TO_LATIN1((U8) c) >= 0xC0 \
- && NATIVE_TO_LATIN1((U8) c) <= 0xDE \
+ && ( IN_RANGE(NATIVE_TO_LATIN1((U8) c), \
+ 0xC0, 0xDE) \
&& NATIVE_TO_LATIN1((U8) c) != 0xD7)))
# define isWORDCHAR_L1(c) (isIDFIRST_L1(c) || isDIGIT_A(c))
# define isIDFIRST_L1(c) (isALPHA_L1(c) || NATIVE_TO_LATIN1(c) == '_')
#define toLOWER(c) (isASCII(c) ? toLOWER_LATIN1(c) : (c))
#define toUPPER(c) (isASCII(c) ? toUPPER_LATIN1_MOD(c) : (c))
which uses table lookup and mask instead of subtraction. (This would
- work because the _MOD does not apply in the ASCII range) */
+ work because the _MOD does not apply in the ASCII range).
+
+ These actually are UTF-8 invariant casing, not just ASCII, as any non-ASCII
+ UTF-8 invariants are neither upper nor lower. (Only on EBCDIC platforms are
+ there non-ASCII invariants, and all of them are controls.) */
#define toLOWER(c) (isUPPER(c) ? (U8)((c) + ('a' - 'A')) : (c))
#define toUPPER(c) (isLOWER(c) ? (U8)((c) - ('a' - 'A')) : (c))
/* In the ASCII range, these are equivalent to what they're here defined to be.
* But by creating these definitions, other code doesn't have to be aware of
- * this detail */
+ * this detail. Actually this works for all UTF-8 invariants, not just the
+ * ASCII range. (EBCDIC platforms can have non-ASCII invariants.) */
#define toFOLD(c) toLOWER(c)
#define toTITLE(c) toUPPER(c)
|| (char)(c) == '_'))
/* These next three are also for internal core Perl use only: case-change
- * helper macros */
+ * helper macros. The reason for using the PL_latin arrays is in case the
+ * system function is defective; it ensures uniform results that conform to the
+ * Unicod standard. It does not handle the anomalies in UTF-8 Turkic locales */
#define _generic_toLOWER_LC(c, function, cast) (! FITS_IN_8_BITS(c) \
? (c) \
: (IN_UTF8_CTYPE_LOCALE) \
? PL_latin1_lc[ (U8) (c) ] \
- : (cast)function((cast)(c)))
+ : (cast)function((cast)(c)))
/* Note that the result can be larger than a byte in a UTF-8 locale. It
* returns a single value, so can't adequately return the upper case of LATIN
* SMALL LETTER SHARP S in a UTF-8 locale (which should be a string of two
* values "SS"); instead it asserts against that under DEBUGGING, and
- * otherwise returns its input */
+ * otherwise returns its input. It does not handle the anomalies in UTF-8
+ * Turkic locales. */
#define _generic_toUPPER_LC(c, function, cast) \
(! FITS_IN_8_BITS(c) \
? (c) \
* returns a single value, so can't adequately return the fold case of LATIN
* SMALL LETTER SHARP S in a UTF-8 locale (which should be a string of two
* values "ss"); instead it asserts against that under DEBUGGING, and
- * otherwise returns its input */
+ * otherwise returns its input. It does not handle the anomalies in UTF-8
+ * Turkic locales */
#define _generic_toFOLD_LC(c, function, cast) \
((UNLIKELY((c) == MICRO_SIGN) && IN_UTF8_CTYPE_LOCALE) \
? GREEK_SMALL_LETTER_MU \
? 0 /* Note that doesn't check validity for latin1 */ \
: above_latin1)
-/* NOTE that some of these macros have very similar ones in regcharclass.h.
- * For example, there is (at the time of this writing) an 'is_SPACE_utf8()'
- * there, differing in name only by an underscore from the one here
- * 'isSPACE_utf8(). The difference is that the ones here are probably more
- * efficient and smaller, using an O(1) array lookup for Latin1-range code
- * points; the regcharclass.h ones are implemented as a series of
- * "if-else-if-else ..." */
#define isALPHA_utf8(p) _generic_utf8(ALPHA, p)
#define isALPHANUMERIC_utf8(p) _generic_utf8(ALPHANUMERIC, p)
#define isOCTAL_L1(c) isOCTAL_A(c)
#define isXDIGIT_L1(c) isXDIGIT_A(c)
#define isALNUM(c) isWORDCHAR(c)
+#define isALNUM_A(c) isALNUM(c)
#define isALNUMU(c) isWORDCHAR_L1(c)
#define isALNUM_LC(c) isWORDCHAR_LC(c)
#define isALNUM_uni(c) isWORDCHAR_uni(c)
#define NEWSV(x,len) newSV(len)
#endif
-#define MEM_SIZE_MAX ((MEM_SIZE)~0)
+#define MEM_SIZE_MAX ((MEM_SIZE)-1)
+#define _PERL_STRLEN_ROUNDUP_UNCHECKED(n) (((n) - 1 + PERL_STRLEN_ROUNDUP_QUANTUM) & ~((MEM_SIZE)PERL_STRLEN_ROUNDUP_QUANTUM - 1))
#ifdef PERL_MALLOC_WRAP
*/
# define _MEM_WRAP_NEEDS_RUNTIME_CHECK(n,t) \
- (8 * sizeof(n) + sizeof(t) > sizeof(MEM_SIZE))
+ ( sizeof(MEM_SIZE) < sizeof(n) \
+ || sizeof(t) > ((MEM_SIZE)1 << 8*(sizeof(MEM_SIZE) - sizeof(n))))
/* This is written in a slightly odd way to avoid various spurious
* compiler warnings. We *want* to write the expression as
(void)(UNLIKELY(_MEM_WRAP_WILL_WRAP(n,t)) \
&& (Perl_croak_nocontext("%s",(a)),0))
+/* "a" arg must be a string literal */
+# define MEM_WRAP_CHECK_s(n,t,a) \
+ (void)(UNLIKELY(_MEM_WRAP_WILL_WRAP(n,t)) \
+ && (Perl_croak_nocontext("" a ""),0))
+
#define MEM_WRAP_CHECK_(n,t) MEM_WRAP_CHECK(n,t),
-#define PERL_STRLEN_ROUNDUP(n) ((void)(((n) > MEM_SIZE_MAX - 2 * PERL_STRLEN_ROUNDUP_QUANTUM) ? (croak_memory_wrap(),0):0),((n-1+PERL_STRLEN_ROUNDUP_QUANTUM)&~((MEM_SIZE)PERL_STRLEN_ROUNDUP_QUANTUM-1)))
+#define PERL_STRLEN_ROUNDUP(n) ((void)(((n) > MEM_SIZE_MAX - 2 * PERL_STRLEN_ROUNDUP_QUANTUM) ? (croak_memory_wrap(),0) : 0), _PERL_STRLEN_ROUNDUP_UNCHECKED(n))
#else
#define MEM_WRAP_CHECK(n,t)
#define MEM_WRAP_CHECK_1(n,t,a)
-#define MEM_WRAP_CHECK_2(n,t,a,b)
+#define MEM_WRAP_CHECK_s(n,t,a)
#define MEM_WRAP_CHECK_(n,t)
-#define PERL_STRLEN_ROUNDUP(n) (((n-1+PERL_STRLEN_ROUNDUP_QUANTUM)&~((MEM_SIZE)PERL_STRLEN_ROUNDUP_QUANTUM-1)))
+#define PERL_STRLEN_ROUNDUP(n) _PERL_STRLEN_ROUNDUP_UNCHECKED(n)
#endif
#define Safefree(d) safefree(MEM_LOG_FREE((Malloc_t)(d)))
#endif
+/* assert that a valid ptr has been supplied - use this instead of assert(ptr) *
+ * as it handles cases like constant string arguments without throwing warnings *
+ * the cast is required, as is the inequality check, to avoid warnings */
#define perl_assert_ptr(p) assert( ((void*)(p)) != 0 )
#define Copy(s,d,n,t) (MEM_WRAP_CHECK_(n,t) perl_assert_ptr(d), perl_assert_ptr(s), (void)memcpy((char*)(d),(const char*)(s), (n) * sizeof(t)))
#define Zero(d,n,t) (MEM_WRAP_CHECK_(n,t) perl_assert_ptr(d), (void)memzero((char*)(d), (n) * sizeof(t)))
+/* Like above, but returns a pointer to 'd' */
#define MoveD(s,d,n,t) (MEM_WRAP_CHECK_(n,t) perl_assert_ptr(d), perl_assert_ptr(s), memmove((char*)(d),(const char*)(s), (n) * sizeof(t)))
#define CopyD(s,d,n,t) (MEM_WRAP_CHECK_(n,t) perl_assert_ptr(d), perl_assert_ptr(s), memcpy((char*)(d),(const char*)(s), (n) * sizeof(t)))
#define ZeroD(d,n,t) (MEM_WRAP_CHECK_(n,t) perl_assert_ptr(d), memzero((char*)(d), (n) * sizeof(t)))
#define StructCopy(s,d,t) (*((t*)(d)) = *((t*)(s)))
-/* C_ARRAY_LENGTH is the number of elements in the C array (so you
- * want your zero-based indices to be less than but not equal to).
- *
- * C_ARRAY_END is one past the last: half-open/half-closed range,
- * not last-inclusive range. */
+/*
+=head1 Handy Values
+
+=for apidoc Am|STRLEN|C_ARRAY_LENGTH|void *a
+
+Returns the number of elements in the input C array (so you want your
+zero-based indices to be less than but not equal to).
+
+=for apidoc Am|void *|C_ARRAY_END|void *a
+
+Returns a pointer to one element past the final element of the input C array.
+
+=cut
+
+C_ARRAY_END is one past the last: half-open/half-closed range, not
+last-inclusive range.
+*/
#define C_ARRAY_LENGTH(a) (sizeof(a)/sizeof((a)[0]))
#define C_ARRAY_END(a) ((a) + C_ARRAY_LENGTH(a))