This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Use UINTMAX_C() in nBIT_MASK() definition
[perl5.git] / handy.h
1 /*    handy.h
2  *
3  *    Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1999, 2000,
4  *    2001, 2002, 2004, 2005, 2006, 2007, 2008, 2012 by Larry Wall and others
5  *
6  *    You may distribute under the terms of either the GNU General Public
7  *    License or the Artistic License, as specified in the README file.
8  *
9  */
10
11 /* IMPORTANT NOTE: Everything whose name begins with an underscore is for
12  * internal core Perl use only. */
13
14 #ifndef PERL_HANDY_H_ /* Guard against nested #inclusion */
15 #define PERL_HANDY_H_
16
17 #ifndef PERL_CORE
18 #  define Null(type) ((type)NULL)
19
20 /*
21 =head1 Handy Values
22
23 =for apidoc AmnU||Nullch
24 Null character pointer.  (No longer available when C<PERL_CORE> is
25 defined.)
26
27 =for apidoc AmnU||Nullsv
28 Null SV pointer.  (No longer available when C<PERL_CORE> is defined.)
29
30 =cut
31 */
32
33 #  define Nullch Null(char*)
34 #  define Nullfp Null(PerlIO*)
35 #  define Nullsv Null(SV*)
36 #endif
37
38 #ifdef TRUE
39 #undef TRUE
40 #endif
41 #ifdef FALSE
42 #undef FALSE
43 #endif
44 #define TRUE (1)
45 #define FALSE (0)
46
47 /* The MUTABLE_*() macros cast pointers to the types shown, in such a way
48  * (compiler permitting) that casting away const-ness will give a warning;
49  * e.g.:
50  *
51  * const SV *sv = ...;
52  * AV *av1 = (AV*)sv;        <== BAD:  the const has been silently cast away
53  * AV *av2 = MUTABLE_AV(sv); <== GOOD: it may warn
54  */
55
56 #if defined(__GNUC__) && !defined(PERL_GCC_BRACE_GROUPS_FORBIDDEN)
57 #  define MUTABLE_PTR(p) ({ void *p_ = (p); p_; })
58 #else
59 #  define MUTABLE_PTR(p) ((void *) (p))
60 #endif
61
62 #define MUTABLE_AV(p)   ((AV *)MUTABLE_PTR(p))
63 #define MUTABLE_CV(p)   ((CV *)MUTABLE_PTR(p))
64 #define MUTABLE_GV(p)   ((GV *)MUTABLE_PTR(p))
65 #define MUTABLE_HV(p)   ((HV *)MUTABLE_PTR(p))
66 #define MUTABLE_IO(p)   ((IO *)MUTABLE_PTR(p))
67 #define MUTABLE_SV(p)   ((SV *)MUTABLE_PTR(p))
68
69 #if defined(I_STDBOOL) && !defined(PERL_BOOL_AS_CHAR)
70 #  include <stdbool.h>
71 #  ifndef HAS_BOOL
72 #    define HAS_BOOL 1
73 #  endif
74 #endif
75
76 /* bool is built-in for g++-2.6.3 and later, which might be used
77    for extensions.  <_G_config.h> defines _G_HAVE_BOOL, but we can't
78    be sure _G_config.h will be included before this file.  _G_config.h
79    also defines _G_HAVE_BOOL for both gcc and g++, but only g++
80    actually has bool.  Hence, _G_HAVE_BOOL is pretty useless for us.
81    g++ can be identified by __GNUG__.
82    Andy Dougherty       February 2000
83 */
84 #ifdef __GNUG__         /* GNU g++ has bool built-in */
85 # ifndef PERL_BOOL_AS_CHAR
86 #  ifndef HAS_BOOL
87 #    define HAS_BOOL 1
88 #  endif
89 # endif
90 #endif
91
92 #ifndef HAS_BOOL
93 # ifdef bool
94 #  undef bool
95 # endif
96 # define bool char
97 # define HAS_BOOL 1
98 #endif
99
100 /*
101 =for apidoc Am|bool|cBOOL|bool expr
102
103 Cast-to-bool.  A simple S<C<(bool) I<expr>>> cast may not do the right thing:
104 if C<bool> is defined as C<char>, for example, then the cast from C<int> is
105 implementation-defined.
106
107 C<(bool)!!(cbool)> in a ternary triggers a bug in xlc on AIX
108
109 =cut
110 */
111 #define cBOOL(cbool) ((cbool) ? (bool)1 : (bool)0)
112
113 /* Try to figure out __func__ or __FUNCTION__ equivalent, if any.
114  * XXX Should really be a Configure probe, with HAS__FUNCTION__
115  *     and FUNCTION__ as results.
116  * XXX Similarly, a Configure probe for __FILE__ and __LINE__ is needed. */
117 #if (defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L) || (defined(__SUNPRO_C)) /* C99 or close enough. */
118 #  define FUNCTION__ __func__
119 #elif (defined(__DECC_VER)) /* Tru64 or VMS, and strict C89 being used, but not modern enough cc (in Tur64, -c99 not known, only -std1). */
120 #  define FUNCTION__ ""
121 #else
122 #  define FUNCTION__ __FUNCTION__ /* Common extension. */
123 #endif
124
125 /* XXX A note on the perl source internal type system.  The
126    original intent was that I32 be *exactly* 32 bits.
127
128    Currently, we only guarantee that I32 is *at least* 32 bits.
129    Specifically, if int is 64 bits, then so is I32.  (This is the case
130    for the Cray.)  This has the advantage of meshing nicely with
131    standard library calls (where we pass an I32 and the library is
132    expecting an int), but the disadvantage that an I32 is not 32 bits.
133    Andy Dougherty       August 1996
134
135    There is no guarantee that there is *any* integral type with
136    exactly 32 bits.  It is perfectly legal for a system to have
137    sizeof(short) == sizeof(int) == sizeof(long) == 8.
138
139    Similarly, there is no guarantee that I16 and U16 have exactly 16
140    bits.
141
142    For dealing with issues that may arise from various 32/64-bit
143    systems, we will ask Configure to check out
144
145         SHORTSIZE == sizeof(short)
146         INTSIZE == sizeof(int)
147         LONGSIZE == sizeof(long)
148         LONGLONGSIZE == sizeof(long long) (if HAS_LONG_LONG)
149         PTRSIZE == sizeof(void *)
150         DOUBLESIZE == sizeof(double)
151         LONG_DOUBLESIZE == sizeof(long double) (if HAS_LONG_DOUBLE).
152
153 */
154
155 #ifdef I_INTTYPES /* e.g. Linux has int64_t without <inttypes.h> */
156 #   include <inttypes.h>
157 #   ifdef INT32_MIN_BROKEN
158 #       undef  INT32_MIN
159 #       define INT32_MIN (-2147483647-1)
160 #   endif
161 #   ifdef INT64_MIN_BROKEN
162 #       undef  INT64_MIN
163 #       define INT64_MIN (-9223372036854775807LL-1)
164 #   endif
165 #endif
166
167 typedef I8TYPE I8;
168 typedef U8TYPE U8;
169 typedef I16TYPE I16;
170 typedef U16TYPE U16;
171 typedef I32TYPE I32;
172 typedef U32TYPE U32;
173
174 #ifdef QUADKIND
175 typedef I64TYPE I64;
176 typedef U64TYPE U64;
177 #endif
178
179 #if defined(UINT8_MAX) && defined(INT16_MAX) && defined(INT32_MAX)
180
181 /* I8_MAX and I8_MIN constants are not defined, as I8 is an ambiguous type.
182    Please search CHAR_MAX in perl.h for further details. */
183 #define U8_MAX UINT8_MAX
184 #define U8_MIN UINT8_MIN
185
186 #define I16_MAX INT16_MAX
187 #define I16_MIN INT16_MIN
188 #define U16_MAX UINT16_MAX
189 #define U16_MIN UINT16_MIN
190
191 #define I32_MAX INT32_MAX
192 #define I32_MIN INT32_MIN
193 #ifndef UINT32_MAX_BROKEN /* e.g. HP-UX with gcc messes this up */
194 #  define U32_MAX UINT32_MAX
195 #else
196 #  define U32_MAX 4294967295U
197 #endif
198 #define U32_MIN UINT32_MIN
199
200 #else
201
202 /* I8_MAX and I8_MIN constants are not defined, as I8 is an ambiguous type.
203    Please search CHAR_MAX in perl.h for further details. */
204 #define U8_MAX PERL_UCHAR_MAX
205 #define U8_MIN PERL_UCHAR_MIN
206
207 #define I16_MAX PERL_SHORT_MAX
208 #define I16_MIN PERL_SHORT_MIN
209 #define U16_MAX PERL_USHORT_MAX
210 #define U16_MIN PERL_USHORT_MIN
211
212 #if LONGSIZE > 4
213 # define I32_MAX PERL_INT_MAX
214 # define I32_MIN PERL_INT_MIN
215 # define U32_MAX PERL_UINT_MAX
216 # define U32_MIN PERL_UINT_MIN
217 #else
218 # define I32_MAX PERL_LONG_MAX
219 # define I32_MIN PERL_LONG_MIN
220 # define U32_MAX PERL_ULONG_MAX
221 # define U32_MIN PERL_ULONG_MIN
222 #endif
223
224 #endif
225
226 /* These C99 typedefs are useful sometimes for, say, loop variables whose
227  * maximum values are small, but for which speed trumps size.  If we have a C99
228  * compiler, use that.  Otherwise, a plain 'int' should be good enough.
229  *
230  * Restrict these to core for now until we are more certain this is a good
231  * idea. */
232 #if defined(PERL_CORE) || defined(PERL_EXT)
233 #  ifdef I_STDINT
234     typedef  int_fast8_t  PERL_INT_FAST8_T;
235     typedef uint_fast8_t  PERL_UINT_FAST8_T;
236     typedef  int_fast16_t PERL_INT_FAST16_T;
237     typedef uint_fast16_t PERL_UINT_FAST16_T;
238 #  else
239     typedef int           PERL_INT_FAST8_T;
240     typedef unsigned int  PERL_UINT_FAST8_T;
241     typedef int           PERL_INT_FAST16_T;
242     typedef unsigned int  PERL_UINT_FAST16_T;
243 #  endif
244 #endif
245
246 /* log(2) (i.e., log base 10 of 2) is pretty close to 0.30103, just in case
247  * anyone is grepping for it.  So BIT_DIGITS gives the number of decimal digits
248  * required to represent any possible unsigned number containing N bits.
249  * TYPE_DIGITS gives the number of decimal digits required to represent any
250  * possible unsigned number of type T. */
251 #define BIT_DIGITS(N)   (((N)*146)/485 + 1)  /* log10(2) =~ 146/485 */
252 #define TYPE_DIGITS(T)  BIT_DIGITS(sizeof(T) * 8)
253 #define TYPE_CHARS(T)   (TYPE_DIGITS(T) + 2) /* sign, NUL */
254
255 /* Unused by core; should be deprecated */
256 #define Ctl(ch) ((ch) & 037)
257
258 #if defined(PERL_CORE) || defined(PERL_EXT)
259 #  ifndef MIN
260 #    define MIN(a,b) ((a) < (b) ? (a) : (b))
261 #  endif
262 #  ifndef MAX
263 #    define MAX(a,b) ((a) > (b) ? (a) : (b))
264 #  endif
265 #endif
266
267 /* Returns a boolean as to whether the input unsigned number is a power of 2
268  * (2**0, 2**1, etc).  In other words if it has just a single bit set.
269  * If not, subtracting 1 would leave the uppermost bit set, so the & would
270  * yield non-zero */
271 #if defined(PERL_CORE) || defined(PERL_EXT)
272 #  define isPOWER_OF_2(n) ((n) && ((n) & ((n)-1)) == 0)
273 #endif
274
275 /* Returns a mask with the lowest n bits set */
276 #define nBIT_MASK(n) ((UINTMAX_C(1) << (n)) - 1)
277
278 /* The largest unsigned number that will fit into n bits */
279 #define nBIT_UMAX(n)  nBIT_MASK(n)
280
281 /*
282 =for apidoc Am|void|__ASSERT_|bool expr
283
284 This is a helper macro to avoid preprocessor issues, replaced by nothing
285 unless under DEBUGGING, where it expands to an assert of its argument,
286 followed by a comma (hence the comma operator).  If we just used a straight
287 assert(), we would get a comma with nothing before it when not DEBUGGING.
288
289 =cut
290
291 We also use empty definition under Coverity since the __ASSERT__
292 checks often check for things that Really Cannot Happen, and Coverity
293 detects that and gets all excited. */
294
295 #if   defined(DEBUGGING) && !defined(__COVERITY__)                        \
296  && ! defined(PERL_SMALL_MACRO_BUFFER)
297 #   define __ASSERT_(statement)  assert(statement),
298 #else
299 #   define __ASSERT_(statement)
300 #endif
301
302 /*
303 =head1 SV Manipulation Functions
304
305 =for apidoc Ama|SV*|newSVpvs|"literal string"
306 Like C<newSVpvn>, but takes a literal string instead of a
307 string/length pair.
308
309 =for apidoc Ama|SV*|newSVpvs_flags|"literal string"|U32 flags
310 Like C<newSVpvn_flags>, but takes a literal string instead of
311 a string/length pair.
312
313 =for apidoc Ama|SV*|newSVpvs_share|"literal string"
314 Like C<newSVpvn_share>, but takes a literal string instead of
315 a string/length pair and omits the hash parameter.
316
317 =for apidoc Am|void|sv_catpvs_flags|SV* sv|"literal string"|I32 flags
318 Like C<sv_catpvn_flags>, but takes a literal string instead
319 of a string/length pair.
320
321 =for apidoc Am|void|sv_catpvs_nomg|SV* sv|"literal string"
322 Like C<sv_catpvn_nomg>, but takes a literal string instead of
323 a string/length pair.
324
325 =for apidoc Am|void|sv_catpvs|SV* sv|"literal string"
326 Like C<sv_catpvn>, but takes a literal string instead of a
327 string/length pair.
328
329 =for apidoc Am|void|sv_catpvs_mg|SV* sv|"literal string"
330 Like C<sv_catpvn_mg>, but takes a literal string instead of a
331 string/length pair.
332
333 =for apidoc Am|void|sv_setpvs|SV* sv|"literal string"
334 Like C<sv_setpvn>, but takes a literal string instead of a
335 string/length pair.
336
337 =for apidoc Am|void|sv_setpvs_mg|SV* sv|"literal string"
338 Like C<sv_setpvn_mg>, but takes a literal string instead of a
339 string/length pair.
340
341 =for apidoc Am|SV *|sv_setref_pvs|SV *const rv|const char *const classname|"literal string"
342 Like C<sv_setref_pvn>, but takes a literal string instead of
343 a string/length pair.
344
345 =head1 Memory Management
346
347 =for apidoc Ama|char*|savepvs|"literal string"
348 Like C<savepvn>, but takes a literal string instead of a
349 string/length pair.
350
351 =for apidoc Ama|char*|savesharedpvs|"literal string"
352 A version of C<savepvs()> which allocates the duplicate string in memory
353 which is shared between threads.
354
355 =head1 GV Functions
356
357 =for apidoc Am|HV*|gv_stashpvs|"name"|I32 create
358 Like C<gv_stashpvn>, but takes a literal string instead of a
359 string/length pair.
360
361 =head1 Hash Manipulation Functions
362
363 =for apidoc Am|SV**|hv_fetchs|HV* tb|"key"|I32 lval
364 Like C<hv_fetch>, but takes a literal string instead of a
365 string/length pair.
366
367 =for apidoc Am|SV**|hv_stores|HV* tb|"key"|SV* val
368 Like C<hv_store>, but takes a literal string instead of a
369 string/length pair
370 and omits the hash parameter.
371
372 =head1 Lexer interface
373
374 =for apidoc Amx|void|lex_stuff_pvs|"pv"|U32 flags
375
376 Like L</lex_stuff_pvn>, but takes a literal string instead of
377 a string/length pair.
378
379 =cut
380 */
381
382 /*
383 =head1 Handy Values
384
385 =for apidoc Amu|pair|STR_WITH_LEN|"literal string"
386
387 Returns two comma separated tokens of the input literal string, and its length.
388 This is convenience macro which helps out in some API calls.
389 Note that it can't be used as an argument to macros or functions that under
390 some configurations might be macros, which means that it requires the full
391 Perl_xxx(aTHX_ ...) form for any API calls where it's used.
392
393 =cut
394 */
395
396 #define STR_WITH_LEN(s)  ("" s ""), (sizeof(s)-1)
397
398 /* STR_WITH_LEN() shortcuts */
399 #define newSVpvs(str) Perl_newSVpvn(aTHX_ STR_WITH_LEN(str))
400 #define newSVpvs_flags(str,flags)       \
401     Perl_newSVpvn_flags(aTHX_ STR_WITH_LEN(str), flags)
402 #define newSVpvs_share(str) Perl_newSVpvn_share(aTHX_ STR_WITH_LEN(str), 0)
403 #define sv_catpvs_flags(sv, str, flags) \
404     Perl_sv_catpvn_flags(aTHX_ sv, STR_WITH_LEN(str), flags)
405 #define sv_catpvs_nomg(sv, str) \
406     Perl_sv_catpvn_flags(aTHX_ sv, STR_WITH_LEN(str), 0)
407 #define sv_catpvs(sv, str) \
408     Perl_sv_catpvn_flags(aTHX_ sv, STR_WITH_LEN(str), SV_GMAGIC)
409 #define sv_catpvs_mg(sv, str) \
410     Perl_sv_catpvn_flags(aTHX_ sv, STR_WITH_LEN(str), SV_GMAGIC|SV_SMAGIC)
411 #define sv_setpvs(sv, str) Perl_sv_setpvn(aTHX_ sv, STR_WITH_LEN(str))
412 #define sv_setpvs_mg(sv, str) Perl_sv_setpvn_mg(aTHX_ sv, STR_WITH_LEN(str))
413 #define sv_setref_pvs(rv, classname, str) \
414     Perl_sv_setref_pvn(aTHX_ rv, classname, STR_WITH_LEN(str))
415 #define savepvs(str) Perl_savepvn(aTHX_ STR_WITH_LEN(str))
416 #define savesharedpvs(str) Perl_savesharedpvn(aTHX_ STR_WITH_LEN(str))
417 #define gv_stashpvs(str, create) \
418     Perl_gv_stashpvn(aTHX_ STR_WITH_LEN(str), create)
419 #define gv_fetchpvs(namebeg, add, sv_type) \
420     Perl_gv_fetchpvn_flags(aTHX_ STR_WITH_LEN(namebeg), add, sv_type)
421 #define gv_fetchpvn(namebeg, len, add, sv_type) \
422     Perl_gv_fetchpvn_flags(aTHX_ namebeg, len, add, sv_type)
423 #define sv_catxmlpvs(dsv, str, utf8) \
424     Perl_sv_catxmlpvn(aTHX_ dsv, STR_WITH_LEN(str), utf8)
425
426
427 #define lex_stuff_pvs(pv,flags) Perl_lex_stuff_pvn(aTHX_ STR_WITH_LEN(pv), flags)
428
429 #define get_cvs(str, flags)                                     \
430         Perl_get_cvn_flags(aTHX_ STR_WITH_LEN(str), (flags))
431
432 /* internal helpers */
433 #define PERL_RVS_TO_DECIMAL_(r,v,s) (((r)*1000000)+((v)*1000)+(s))
434 #define PERL_DECIMAL_VERSION_                                               \
435         PERL_RVS_TO_DECIMAL_(PERL_REVISION, PERL_VERSION, PERL_SUBVERSION)
436
437 /*
438 =for apidoc AmR|bool|PERL_VERSION_EQ|const int r|const int v|const int s
439
440 Returns whether or not the perl currently executing has the specified
441 relationship to the perl given by the parameters.  For example,
442
443  #if PERL_VERSION_GT(5,24,2)
444    code that will only be compiled on perls after v5.24.2
445  #else
446    fallback code
447  #endif
448
449 Note that this is usable in making compile-time decisions
450
451 The possible comparisons are C<PERL_VERSION_EQ>, C<PERL_VERSION_NE>,
452 C<PERL_VERSION_GE>, C<PERL_VERSION_GT>, C<PERL_VERSION_LE>, and
453 C<PERL_VERSION_LT>.
454
455 =for apidoc AmRh|bool|PERL_VERSION_NE|const int r|const int v|const int s
456 =for apidoc AmRh|bool|PERL_VERSION_GE|const int r|const int v|const int s
457 =for apidoc AmRh|bool|PERL_VERSION_GT|const int r|const int v|const int s
458 =for apidoc AmRh|bool|PERL_VERSION_LE|const int r|const int v|const int s
459 =for apidoc AmRh|bool|PERL_VERSION_LT|const int r|const int v|const int s
460
461 =cut
462 */
463
464 # define PERL_VERSION_EQ(r,v,s) (PERL_DECIMAL_VERSION_ == PERL_RVS_TO_DECIMAL_(r,v,s))
465 # define PERL_VERSION_NE(r,v,s) (! PERL_VERSION_EQ(r,v,s))
466 # define PERL_VERSION_LT(r,v,s) (PERL_DECIMAL_VERSION_ < PERL_RVS_TO_DECIMAL_(r,v,s))
467 # define PERL_VERSION_LE(r,v,s) (PERL_DECIMAL_VERSION_ <= PERL_RVS_TO_DECIMAL_(r,v,s))
468 # define PERL_VERSION_GT(r,v,s) (! PERL_VERSION_LE(r,v,s))
469 # define PERL_VERSION_GE(r,v,s) (! PERL_VERSION_LT(r,v,s))
470
471 /*
472 =head1 Miscellaneous Functions
473
474 =for apidoc Am|bool|strNE|char* s1|char* s2
475 Test two C<NUL>-terminated strings to see if they are different.  Returns true
476 or false.
477
478 =for apidoc Am|bool|strEQ|char* s1|char* s2
479 Test two C<NUL>-terminated strings to see if they are equal.  Returns true or
480 false.
481
482 =for apidoc Am|bool|strLT|char* s1|char* s2
483 Test two C<NUL>-terminated strings to see if the first, C<s1>, is less than the
484 second, C<s2>.  Returns true or false.
485
486 =for apidoc Am|bool|strLE|char* s1|char* s2
487 Test two C<NUL>-terminated strings to see if the first, C<s1>, is less than or
488 equal to the second, C<s2>.  Returns true or false.
489
490 =for apidoc Am|bool|strGT|char* s1|char* s2
491 Test two C<NUL>-terminated strings to see if the first, C<s1>, is greater than
492 the second, C<s2>.  Returns true or false.
493
494 =for apidoc Am|bool|strGE|char* s1|char* s2
495 Test two C<NUL>-terminated strings to see if the first, C<s1>, is greater than
496 or equal to the second, C<s2>.  Returns true or false.
497
498 =for apidoc Am|bool|strnNE|char* s1|char* s2|STRLEN len
499 Test two C<NUL>-terminated strings to see if they are different.  The C<len>
500 parameter indicates the number of bytes to compare.  Returns true or false.  (A
501 wrapper for C<strncmp>).
502
503 =for apidoc Am|bool|strnEQ|char* s1|char* s2|STRLEN len
504 Test two C<NUL>-terminated strings to see if they are equal.  The C<len>
505 parameter indicates the number of bytes to compare.  Returns true or false.  (A
506 wrapper for C<strncmp>).
507
508 =for apidoc Am|bool|memEQ|char* s1|char* s2|STRLEN len
509 Test two buffers (which may contain embedded C<NUL> characters, to see if they
510 are equal.  The C<len> parameter indicates the number of bytes to compare.
511 Returns zero if equal, or non-zero if non-equal.
512
513 =for apidoc Am|bool|memEQs|char* s1|STRLEN l1|"s2"
514 Like L</memEQ>, but the second string is a literal enclosed in double quotes,
515 C<l1> gives the number of bytes in C<s1>.
516 Returns zero if equal, or non-zero if non-equal.
517
518 =for apidoc Am|bool|memNE|char* s1|char* s2|STRLEN len
519 Test two buffers (which may contain embedded C<NUL> characters, to see if they
520 are not equal.  The C<len> parameter indicates the number of bytes to compare.
521 Returns zero if non-equal, or non-zero if equal.
522
523 =for apidoc Am|bool|memNEs|char* s1|STRLEN l1|"s2"
524 Like L</memNE>, but the second string is a literal enclosed in double quotes,
525 C<l1> gives the number of bytes in C<s1>.
526 Returns zero if non-equal, or zero if non-equal.
527
528 =for apidoc Am|bool|memCHRs|"list"|char c
529 Returns the position of the first occurence of the byte C<c> in the literal
530 string C<"list">, or NULL if C<c> doesn't appear in C<"list">.  All bytes are
531 treated as unsigned char.  Thus this macro can be used to determine if C<c> is
532 in a set of particular characters.  Unlike L<strchr(3)>, it works even if C<c>
533 is C<NUL> (and the set doesn't include C<NUL>).
534
535 =cut
536
537 New macros should use the following conventions for their names (which are
538 based on the underlying C library functions):
539
540   (mem | str n? ) (EQ | NE | LT | GT | GE | (( BEGIN | END ) P? )) l? s?
541
542   Each has two main parameters, string-like operands that are compared
543   against each other, as specified by the macro name.  Some macros may
544   additionally have one or potentially even two length parameters.  If a length
545   parameter applies to both string parameters, it will be positioned third;
546   otherwise any length parameter immediately follows the string parameter it
547   applies to.
548
549   If the prefix to the name is 'str', the string parameter is a pointer to a C
550   language string.  Such a string does not contain embedded NUL bytes; its
551   length may be unknown, but can be calculated by C<strlen()>, since it is
552   terminated by a NUL, which isn't included in its length.
553
554   The optional 'n' following 'str' means that there is a third parameter,
555   giving the maximum number of bytes to look at in each string.  Even if both
556   strings are longer than the length parameter, those extra bytes will be
557   unexamined.
558
559   The 's' suffix means that the 2nd byte string parameter is a literal C
560   double-quoted string.  Its length will automatically be calculated by the
561   macro, so no length parameter will ever be needed for it.
562
563   If the prefix is 'mem', the string parameters don't have to be C strings;
564   they may contain embedded NUL bytes, do not necessarily have a terminating
565   NUL, and their lengths can be known only through other means, which in
566   practice are additional parameter(s) passed to the function.  All 'mem'
567   functions have at least one length parameter.  Barring any 'l' or 's' suffix,
568   there is a single length parameter, in position 3, which applies to both
569   string parameters.  The 's' suffix means, as described above, that the 2nd
570   string is a literal double-quoted C string (hence its length is calculated by
571   the macro, and the length parameter to the function applies just to the first
572   string parameter, and hence is positioned just after it).  An 'l' suffix
573   means that the 2nd string parameter has its own length parameter, and the
574   signature will look like memFOOl(s1, l1, s2, l2).
575
576   BEGIN (and END) are for testing if the 2nd string is an initial (or final)
577   substring  of the 1st string.  'P' if present indicates that the substring
578   must be a "proper" one in tha mathematical sense that the first one must be
579   strictly larger than the 2nd.
580
581 */
582
583
584 #define strNE(s1,s2) (strcmp(s1,s2) != 0)
585 #define strEQ(s1,s2) (strcmp(s1,s2) == 0)
586 #define strLT(s1,s2) (strcmp(s1,s2) < 0)
587 #define strLE(s1,s2) (strcmp(s1,s2) <= 0)
588 #define strGT(s1,s2) (strcmp(s1,s2) > 0)
589 #define strGE(s1,s2) (strcmp(s1,s2) >= 0)
590
591 #define strnNE(s1,s2,l) (strncmp(s1,s2,l) != 0)
592 #define strnEQ(s1,s2,l) (strncmp(s1,s2,l) == 0)
593
594 #define memEQ(s1,s2,l) (memcmp(((const void *) (s1)), ((const void *) (s2)), l) == 0)
595 #define memNE(s1,s2,l) (! memEQ(s1,s2,l))
596
597 /* memEQ and memNE where second comparand is a string constant */
598 #define memEQs(s1, l, s2) \
599         (((sizeof(s2)-1) == (l)) && memEQ((s1), ("" s2 ""), (sizeof(s2)-1)))
600 #define memNEs(s1, l, s2) (! memEQs(s1, l, s2))
601
602 /* Keep these private until we decide it was a good idea */
603 #if defined(PERL_CORE) || defined(PERL_EXT) || defined(PERL_EXT_POSIX)
604
605 #define strBEGINs(s1,s2) (strncmp(s1,"" s2 "", sizeof(s2)-1) == 0)
606
607 #define memBEGINs(s1, l, s2)                                                \
608             (   (Ptrdiff_t) (l) >= (Ptrdiff_t) sizeof(s2) - 1               \
609              && memEQ(s1, "" s2 "", sizeof(s2)-1))
610 #define memBEGINPs(s1, l, s2)                                               \
611             (   (Ptrdiff_t) (l) > (Ptrdiff_t) sizeof(s2) - 1                \
612              && memEQ(s1, "" s2 "", sizeof(s2)-1))
613 #define memENDs(s1, l, s2)                                                  \
614             (   (Ptrdiff_t) (l) >= (Ptrdiff_t) sizeof(s2) - 1               \
615              && memEQ(s1 + (l) - (sizeof(s2) - 1), "" s2 "", sizeof(s2)-1))
616 #define memENDPs(s1, l, s2)                                                 \
617             (   (Ptrdiff_t) (l) > (Ptrdiff_t) sizeof(s2)                    \
618              && memEQ(s1 + (l) - (sizeof(s2) - 1), "" s2 "", sizeof(s2)-1))
619 #endif  /* End of making macros private */
620
621 #define memLT(s1,s2,l) (memcmp(s1,s2,l) < 0)
622 #define memLE(s1,s2,l) (memcmp(s1,s2,l) <= 0)
623 #define memGT(s1,s2,l) (memcmp(s1,s2,l) > 0)
624 #define memGE(s1,s2,l) (memcmp(s1,s2,l) >= 0)
625
626 #define memCHRs(s1,c) ((const char *) memchr("" s1 "" , c, sizeof(s1)-1))
627
628 /*
629  * Character classes.
630  *
631  * Unfortunately, the introduction of locales means that we
632  * can't trust isupper(), etc. to tell the truth.  And when
633  * it comes to /\w+/ with tainting enabled, we *must* be able
634  * to trust our character classes.
635  *
636  * Therefore, the default tests in the text of Perl will be
637  * independent of locale.  Any code that wants to depend on
638  * the current locale will use the tests that begin with "lc".
639  */
640
641 #ifdef HAS_SETLOCALE  /* XXX Is there a better test for this? */
642 #  ifndef CTYPE256
643 #    define CTYPE256
644 #  endif
645 #endif
646
647 /*
648
649 =head1 Character classification
650 This section is about functions (really macros) that classify characters
651 into types, such as punctuation versus alphabetic, etc.  Most of these are
652 analogous to regular expression character classes.  (See
653 L<perlrecharclass/POSIX Character Classes>.)  There are several variants for
654 each class.  (Not all macros have all variants; each item below lists the
655 ones valid for it.)  None are affected by C<use bytes>, and only the ones
656 with C<LC> in the name are affected by the current locale.
657
658 The base function, e.g., C<isALPHA()>, takes any signed or unsigned value,
659 treating it as a code point, and returns a boolean as to whether or not the
660 character represented by it is (or on non-ASCII platforms, corresponds to) an
661 ASCII character in the named class based on platform, Unicode, and Perl rules.
662 If the input is a number that doesn't fit in an octet, FALSE is returned.
663
664 Variant C<isI<FOO>_A> (e.g., C<isALPHA_A()>) is identical to the base function
665 with no suffix C<"_A">.  This variant is used to emphasize by its name that
666 only ASCII-range characters can return TRUE.
667
668 Variant C<isI<FOO>_L1> imposes the Latin-1 (or EBCDIC equivalent) character set
669 onto the platform.  That is, the code points that are ASCII are unaffected,
670 since ASCII is a subset of Latin-1.  But the non-ASCII code points are treated
671 as if they are Latin-1 characters.  For example, C<isWORDCHAR_L1()> will return
672 true when called with the code point 0xDF, which is a word character in both
673 ASCII and EBCDIC (though it represents different characters in each).
674 If the input is a number that doesn't fit in an octet, FALSE is returned.
675 (Perl's documentation uses a colloquial definition of Latin-1, to include all
676 code points below 256.)
677
678 Variant C<isI<FOO>_uvchr> is exactly like the C<isI<FOO>_L1> variant, for
679 inputs below 256, but if the code point is larger than 255, Unicode rules are
680 used to determine if it is in the character class.  For example,
681 C<isWORDCHAR_uvchr(0x100)> returns TRUE, since 0x100 is LATIN CAPITAL LETTER A
682 WITH MACRON in Unicode, and is a word character.
683
684 Variants C<isI<FOO>_utf8> and C<isI<FOO>_utf8_safe> are like C<isI<FOO>_uvchr>,
685 but are used for UTF-8 encoded strings.  The two forms are different names for
686 the same thing.  Each call to one of these classifies the first character of
687 the string starting at C<p>.  The second parameter, C<e>, points to anywhere in
688 the string beyond the first character, up to one byte past the end of the
689 entire string.  Although both variants are identical, the suffix C<_safe> in
690 one name emphasizes that it will not attempt to read beyond S<C<e - 1>>,
691 provided that the constraint S<C<s E<lt> e>> is true (this is asserted for in
692 C<-DDEBUGGING> builds).  If the UTF-8 for the input character is malformed in
693 some way, the program may croak, or the function may return FALSE, at the
694 discretion of the implementation, and subject to change in future releases.
695
696 Variant C<isI<FOO>_LC> is like the C<isI<FOO>_A> and C<isI<FOO>_L1> variants,
697 but the result is based on the current locale, which is what C<LC> in the name
698 stands for.  If Perl can determine that the current locale is a UTF-8 locale,
699 it uses the published Unicode rules; otherwise, it uses the C library function
700 that gives the named classification.  For example, C<isDIGIT_LC()> when not in
701 a UTF-8 locale returns the result of calling C<isdigit()>.  FALSE is always
702 returned if the input won't fit into an octet.  On some platforms where the C
703 library function is known to be defective, Perl changes its result to follow
704 the POSIX standard's rules.
705
706 Variant C<isI<FOO>_LC_uvchr> acts exactly like C<isI<FOO>_LC> for inputs less
707 than 256, but for larger ones it returns the Unicode classification of the code
708 point.
709
710 Variants C<isI<FOO>_LC_utf8> and C<isI<FOO>_LC_utf8_safe> are like
711 C<isI<FOO>_LC_uvchr>, but are used for UTF-8 encoded strings.  The two forms
712 are different names for the same thing.  Each call to one of these classifies
713 the first character of the string starting at C<p>.  The second parameter,
714 C<e>, points to anywhere in the string beyond the first character, up to one
715 byte past the end of the entire string.  Although both variants are identical,
716 the suffix C<_safe> in one name emphasizes that it will not attempt to read
717 beyond S<C<e - 1>>, provided that the constraint S<C<s E<lt> e>> is true (this
718 is asserted for in C<-DDEBUGGING> builds).  If the UTF-8 for the input
719 character is malformed in some way, the program may croak, or the function may
720 return FALSE, at the discretion of the implementation, and subject to change in
721 future releases.
722
723 =for apidoc Am|bool|isALPHA|int ch
724 Returns a boolean indicating whether the specified input is one of C<[A-Za-z]>,
725 analogous to C<m/[[:alpha:]]/>.
726 See the L<top of this section|/Character classification> for an explanation of
727 variants
728 C<isALPHA_A>, C<isALPHA_L1>, C<isALPHA_uvchr>, C<isALPHA_utf8>,
729 C<isALPHA_utf8_safe>, C<isALPHA_LC>, C<isALPHA_LC_uvchr>, C<isALPHA_LC_utf8>,
730 and C<isALPHA_LC_utf8_safe>.
731
732 =cut
733
734 Here and below, we add the protoypes of these macros for downstream programs
735 that would be interested in them, such as Devel::PPPort
736
737 =for apidoc Amh|bool|isALPHA_A|int ch
738 =for apidoc Amh|bool|isALPHA_L1|int ch
739 =for apidoc Amh|bool|isALPHA_uvchr|int ch
740 =for apidoc Amh|bool|isALPHA_utf8_safe|U8 * s|U8 * end
741 =for apidoc Amh|bool|isALPHA_utf8|U8 * s|U8 * end
742 =for apidoc Amh|bool|isALPHA_LC|int ch
743 =for apidoc Amh|bool|isALPHA_LC_uvchr|int ch
744 =for apidoc Amh|bool|isALPHA_LC_utf8_safe|U8 * s| U8 *end
745
746 =for apidoc Am|bool|isALPHANUMERIC|int ch
747 Returns a boolean indicating whether the specified character is one of
748 C<[A-Za-z0-9]>, analogous to C<m/[[:alnum:]]/>.
749 See the L<top of this section|/Character classification> for an explanation of
750 variants
751 C<isALPHANUMERIC_A>, C<isALPHANUMERIC_L1>, C<isALPHANUMERIC_uvchr>,
752 C<isALPHANUMERIC_utf8>, C<isALPHANUMERIC_utf8_safe>, C<isALPHANUMERIC_LC>,
753 C<isALPHANUMERIC_LC_uvchr>, C<isALPHANUMERIC_LC_utf8>, and
754 C<isALPHANUMERIC_LC_utf8_safe>.
755
756 A (discouraged from use) synonym is C<isALNUMC> (where the C<C> suffix means
757 this corresponds to the C language alphanumeric definition).  Also
758 there are the variants
759 C<isALNUMC_A>, C<isALNUMC_L1>
760 C<isALNUMC_LC>, and C<isALNUMC_LC_uvchr>.
761
762 =for apidoc Amh|bool|isALPHANUMERIC_A|int ch
763 =for apidoc Amh|bool|isALPHANUMERIC_L1|int ch
764 =for apidoc Amh|bool|isALPHANUMERIC_uvchr|int ch
765 =for apidoc Amh|bool|isALPHANUMERIC_utf8_safe|U8 * s|U8 * end
766 =for apidoc Amh|bool|isALPHANUMERIC_utf8|U8 * s|U8 * end
767 =for apidoc Amh|bool|isALPHANUMERIC_LC|int ch
768 =for apidoc Amh|bool|isALPHANUMERIC_LC_uvchr|int ch
769 =for apidoc Amh|bool|isALPHANUMERIC_LC_utf8_safe|U8 * s| U8 *end
770 =for apidoc Amh|bool|isALNUMC|int ch
771 =for apidoc Amh|bool|isALNUMC_A|int ch
772 =for apidoc Amh|bool|isALNUMC_L1|int ch
773 =for apidoc Amh|bool|isALNUMC_LC|int ch
774 =for apidoc Amh|bool|isALNUMC_LC_uvchr|int ch
775
776 =for apidoc Am|bool|isASCII|int ch
777 Returns a boolean indicating whether the specified character is one of the 128
778 characters in the ASCII character set, analogous to C<m/[[:ascii:]]/>.
779 On non-ASCII platforms, it returns TRUE iff this
780 character corresponds to an ASCII character.  Variants C<isASCII_A()> and
781 C<isASCII_L1()> are identical to C<isASCII()>.
782 See the L<top of this section|/Character classification> for an explanation of
783 variants
784 C<isASCII_uvchr>, C<isASCII_utf8>, C<isASCII_utf8_safe>, C<isASCII_LC>,
785 C<isASCII_LC_uvchr>, C<isASCII_LC_utf8>, and C<isASCII_LC_utf8_safe>.
786 Note, however, that some platforms do not have the C library routine
787 C<isascii()>.  In these cases, the variants whose names contain C<LC> are the
788 same as the corresponding ones without.
789
790 =for apidoc Amh|bool|isASCII_A|int ch
791 =for apidoc Amh|bool|isASCII_L1|int ch
792 =for apidoc Amh|bool|isASCII_uvchr|int ch
793 =for apidoc Amh|bool|isASCII_utf8_safe|U8 * s|U8 * end
794 =for apidoc Amh|bool|isASCII_utf8|U8 * s|U8 * end
795 =for apidoc Amh|bool|isASCII_LC|int ch
796 =for apidoc Amh|bool|isASCII_LC_uvchr|int ch
797 =for apidoc Amh|bool|isASCII_LC_utf8_safe|U8 * s| U8 *end
798
799 Also note, that because all ASCII characters are UTF-8 invariant (meaning they
800 have the exact same representation (always a single byte) whether encoded in
801 UTF-8 or not), C<isASCII> will give the correct results when called with any
802 byte in any string encoded or not in UTF-8.  And similarly C<isASCII_utf8> and
803 C<isASCII_utf8_safe> will work properly on any string encoded or not in UTF-8.
804
805 =for apidoc Am|bool|isBLANK|char ch
806 Returns a boolean indicating whether the specified character is a
807 character considered to be a blank, analogous to C<m/[[:blank:]]/>.
808 See the L<top of this section|/Character classification> for an explanation of
809 variants
810 C<isBLANK_A>, C<isBLANK_L1>, C<isBLANK_uvchr>, C<isBLANK_utf8>,
811 C<isBLANK_utf8_safe>, C<isBLANK_LC>, C<isBLANK_LC_uvchr>, C<isBLANK_LC_utf8>,
812 and C<isBLANK_LC_utf8_safe>.  Note,
813 however, that some platforms do not have the C library routine
814 C<isblank()>.  In these cases, the variants whose names contain C<LC> are
815 the same as the corresponding ones without.
816
817 =for apidoc Amh|bool|isBLANK_A|int ch
818 =for apidoc Amh|bool|isBLANK_L1|int ch
819 =for apidoc Amh|bool|isBLANK_uvchr|int ch
820 =for apidoc Amh|bool|isBLANK_utf8_safe|U8 * s|U8 * end
821 =for apidoc Amh|bool|isBLANK_utf8|U8 * s|U8 * end
822 =for apidoc Amh|bool|isBLANK_LC|int ch
823 =for apidoc Amh|bool|isBLANK_LC_uvchr|int ch
824 =for apidoc Amh|bool|isBLANK_LC_utf8_safe|U8 * s| U8 *end
825
826 =for apidoc Am|bool|isCNTRL|char ch
827 Returns a boolean indicating whether the specified character is a
828 control character, analogous to C<m/[[:cntrl:]]/>.
829 See the L<top of this section|/Character classification> for an explanation of
830 variants
831 C<isCNTRL_A>, C<isCNTRL_L1>, C<isCNTRL_uvchr>, C<isCNTRL_utf8>,
832 C<isCNTRL_utf8_safe>, C<isCNTRL_LC>, C<isCNTRL_LC_uvchr>, C<isCNTRL_LC_utf8>
833 and C<isCNTRL_LC_utf8_safe>.  On EBCDIC
834 platforms, you almost always want to use the C<isCNTRL_L1> variant.
835
836 =for apidoc Amh|bool|isCNTRL_A|int ch
837 =for apidoc Amh|bool|isCNTRL_L1|int ch
838 =for apidoc Amh|bool|isCNTRL_uvchr|int ch
839 =for apidoc Amh|bool|isCNTRL_utf8_safe|U8 * s|U8 * end
840 =for apidoc Amh|bool|isCNTRL_utf8|U8 * s|U8 * end
841 =for apidoc Amh|bool|isCNTRL_LC|int ch
842 =for apidoc Amh|bool|isCNTRL_LC_uvchr|int ch
843 =for apidoc Amh|bool|isCNTRL_LC_utf8_safe|U8 * s| U8 *end
844
845 =for apidoc Am|bool|isDIGIT|char ch
846 Returns a boolean indicating whether the specified character is a
847 digit, analogous to C<m/[[:digit:]]/>.
848 Variants C<isDIGIT_A> and C<isDIGIT_L1> are identical to C<isDIGIT>.
849 See the L<top of this section|/Character classification> for an explanation of
850 variants
851 C<isDIGIT_uvchr>, C<isDIGIT_utf8>, C<isDIGIT_utf8_safe>, C<isDIGIT_LC>,
852 C<isDIGIT_LC_uvchr>, C<isDIGIT_LC_utf8>, and C<isDIGIT_LC_utf8_safe>.
853
854 =for apidoc Amh|bool|isDIGIT_A|int ch
855 =for apidoc Amh|bool|isDIGIT_L1|int ch
856 =for apidoc Amh|bool|isDIGIT_uvchr|int ch
857 =for apidoc Amh|bool|isDIGIT_utf8_safe|U8 * s|U8 * end
858 =for apidoc Amh|bool|isDIGIT_utf8|U8 * s|U8 * end
859 =for apidoc Amh|bool|isDIGIT_LC|int ch
860 =for apidoc Amh|bool|isDIGIT_LC_uvchr|int ch
861 =for apidoc Amh|bool|isDIGIT_LC_utf8_safe|U8 * s| U8 *end
862
863 =for apidoc Am|bool|isGRAPH|char ch
864 Returns a boolean indicating whether the specified character is a
865 graphic character, analogous to C<m/[[:graph:]]/>.
866 See the L<top of this section|/Character classification> for an explanation of
867 variants C<isGRAPH_A>, C<isGRAPH_L1>, C<isGRAPH_uvchr>, C<isGRAPH_utf8>,
868 C<isGRAPH_utf8_safe>, C<isGRAPH_LC>, C<isGRAPH_LC_uvchr>,
869 C<isGRAPH_LC_utf8_safe>, and C<isGRAPH_LC_utf8_safe>.
870
871 =for apidoc Amh|bool|isGRAPH_A|int ch
872 =for apidoc Amh|bool|isGRAPH_L1|int ch
873 =for apidoc Amh|bool|isGRAPH_uvchr|int ch
874 =for apidoc Amh|bool|isGRAPH_utf8_safe|U8 * s|U8 * end
875 =for apidoc Amh|bool|isGRAPH_utf8|U8 * s|U8 * end
876 =for apidoc Amh|bool|isGRAPH_LC|int ch
877 =for apidoc Amh|bool|isGRAPH_LC_uvchr|int ch
878 =for apidoc Amh|bool|isGRAPH_LC_utf8_safe|U8 * s| U8 *end
879
880 =for apidoc Am|bool|isLOWER|char ch
881 Returns a boolean indicating whether the specified character is a
882 lowercase character, analogous to C<m/[[:lower:]]/>.
883 See the L<top of this section|/Character classification> for an explanation of
884 variants
885 C<isLOWER_A>, C<isLOWER_L1>, C<isLOWER_uvchr>, C<isLOWER_utf8>,
886 C<isLOWER_utf8_safe>, C<isLOWER_LC>, C<isLOWER_LC_uvchr>, C<isLOWER_LC_utf8>,
887 and C<isLOWER_LC_utf8_safe>.
888
889 =for apidoc Amh|bool|isLOWER_A|int ch
890 =for apidoc Amh|bool|isLOWER_L1|int ch
891 =for apidoc Amh|bool|isLOWER_uvchr|int ch
892 =for apidoc Amh|bool|isLOWER_utf8_safe|U8 * s|U8 * end
893 =for apidoc Amh|bool|isLOWER_utf8|U8 * s|U8 * end
894 =for apidoc Amh|bool|isLOWER_LC|int ch
895 =for apidoc Amh|bool|isLOWER_LC_uvchr|int ch
896 =for apidoc Amh|bool|isLOWER_LC_utf8_safe|U8 * s| U8 *end
897
898 =for apidoc Am|bool|isOCTAL|char ch
899 Returns a boolean indicating whether the specified character is an
900 octal digit, [0-7].
901 The only two variants are C<isOCTAL_A> and C<isOCTAL_L1>; each is identical to
902 C<isOCTAL>.
903
904 =for apidoc Amh|bool|isOCTAL_A|int ch
905 =for apidoc Amh|bool|isOCTAL_L1|int ch
906
907 =for apidoc Am|bool|isPUNCT|char ch
908 Returns a boolean indicating whether the specified character is a
909 punctuation character, analogous to C<m/[[:punct:]]/>.
910 Note that the definition of what is punctuation isn't as
911 straightforward as one might desire.  See L<perlrecharclass/POSIX Character
912 Classes> for details.
913 See the L<top of this section|/Character classification> for an explanation of
914 variants C<isPUNCT_A>, C<isPUNCT_L1>, C<isPUNCT_uvchr>, C<isPUNCT_utf8>,
915 C<isPUNCT_utf8_safe>, C<isPUNCT_LC>, C<isPUNCT_LC_uvchr>, C<isPUNCT_LC_utf8>,
916 and C<isPUNCT_LC_utf8_safe>.
917
918 =for apidoc Amh|bool|isPUNCT_A|int ch
919 =for apidoc Amh|bool|isPUNCT_L1|int ch
920 =for apidoc Amh|bool|isPUNCT_uvchr|int ch
921 =for apidoc Amh|bool|isPUNCT_utf8_safe|U8 * s|U8 * end
922 =for apidoc Amh|bool|isPUNCT_utf8|U8 * s|U8 * end
923 =for apidoc Amh|bool|isPUNCT_LC|int ch
924 =for apidoc Amh|bool|isPUNCT_LC_uvchr|int ch
925 =for apidoc Amh|bool|isPUNCT_LC_utf8_safe|U8 * s| U8 *end
926
927 =for apidoc Am|bool|isSPACE|char ch
928 Returns a boolean indicating whether the specified character is a
929 whitespace character.  This is analogous
930 to what C<m/\s/> matches in a regular expression.  Starting in Perl 5.18
931 this also matches what C<m/[[:space:]]/> does.  Prior to 5.18, only the
932 locale forms of this macro (the ones with C<LC> in their names) matched
933 precisely what C<m/[[:space:]]/> does.  In those releases, the only difference,
934 in the non-locale variants, was that C<isSPACE()> did not match a vertical tab.
935 (See L</isPSXSPC> for a macro that matches a vertical tab in all releases.)
936 See the L<top of this section|/Character classification> for an explanation of
937 variants
938 C<isSPACE_A>, C<isSPACE_L1>, C<isSPACE_uvchr>, C<isSPACE_utf8>,
939 C<isSPACE_utf8_safe>, C<isSPACE_LC>, C<isSPACE_LC_uvchr>, C<isSPACE_LC_utf8>,
940 and C<isSPACE_LC_utf8_safe>.
941
942 =for apidoc Amh|bool|isSPACE_A|int ch
943 =for apidoc Amh|bool|isSPACE_L1|int ch
944 =for apidoc Amh|bool|isSPACE_uvchr|int ch
945 =for apidoc Amh|bool|isSPACE_utf8_safe|U8 * s|U8 * end
946 =for apidoc Amh|bool|isSPACE_utf8|U8 * s|U8 * end
947 =for apidoc Amh|bool|isSPACE_LC|int ch
948 =for apidoc Amh|bool|isSPACE_LC_uvchr|int ch
949 =for apidoc Amh|bool|isSPACE_LC_utf8_safe|U8 * s| U8 *end
950
951 =for apidoc Am|bool|isPSXSPC|char ch
952 (short for Posix Space)
953 Starting in 5.18, this is identical in all its forms to the
954 corresponding C<isSPACE()> macros.
955 The locale forms of this macro are identical to their corresponding
956 C<isSPACE()> forms in all Perl releases.  In releases prior to 5.18, the
957 non-locale forms differ from their C<isSPACE()> forms only in that the
958 C<isSPACE()> forms don't match a Vertical Tab, and the C<isPSXSPC()> forms do.
959 Otherwise they are identical.  Thus this macro is analogous to what
960 C<m/[[:space:]]/> matches in a regular expression.
961 See the L<top of this section|/Character classification> for an explanation of
962 variants C<isPSXSPC_A>, C<isPSXSPC_L1>, C<isPSXSPC_uvchr>, C<isPSXSPC_utf8>,
963 C<isPSXSPC_utf8_safe>, C<isPSXSPC_LC>, C<isPSXSPC_LC_uvchr>,
964 C<isPSXSPC_LC_utf8>, and C<isPSXSPC_LC_utf8_safe>.
965
966 =for apidoc Amh|bool|isPSXSPC_A|int ch
967 =for apidoc Amh|bool|isPSXSPC_L1|int ch
968 =for apidoc Amh|bool|isPSXSPC_uvchr|int ch
969 =for apidoc Amh|bool|isPSXSPC_utf8_safe|U8 * s|U8 * end
970 =for apidoc Amh|bool|isPSXSPC_utf8|U8 * s|U8 * end
971 =for apidoc Amh|bool|isPSXSPC_LC|int ch
972 =for apidoc Amh|bool|isPSXSPC_LC_uvchr|int ch
973 =for apidoc Amh|bool|isPSXSPC_LC_utf8_safe|U8 * s| U8 *end
974
975 =for apidoc Am|bool|isUPPER|char ch
976 Returns a boolean indicating whether the specified character is an
977 uppercase character, analogous to C<m/[[:upper:]]/>.
978 See the L<top of this section|/Character classification> for an explanation of
979 variants C<isUPPER_A>, C<isUPPER_L1>, C<isUPPER_uvchr>, C<isUPPER_utf8>,
980 C<isUPPER_utf8_safe>, C<isUPPER_LC>, C<isUPPER_LC_uvchr>, C<isUPPER_LC_utf8>,
981 and C<isUPPER_LC_utf8_safe>.
982
983 =for apidoc Amh|bool|isUPPER_A|int ch
984 =for apidoc Amh|bool|isUPPER_L1|int ch
985 =for apidoc Amh|bool|isUPPER_uvchr|int ch
986 =for apidoc Amh|bool|isUPPER_utf8_safe|U8 * s|U8 * end
987 =for apidoc Amh|bool|isUPPER_utf8|U8 * s|U8 * end
988 =for apidoc Amh|bool|isUPPER_LC|int ch
989 =for apidoc Amh|bool|isUPPER_LC_uvchr|int ch
990 =for apidoc Amh|bool|isUPPER_LC_utf8_safe|U8 * s| U8 *end
991
992 =for apidoc Am|bool|isPRINT|char ch
993 Returns a boolean indicating whether the specified character is a
994 printable character, analogous to C<m/[[:print:]]/>.
995 See the L<top of this section|/Character classification> for an explanation of
996 variants
997 C<isPRINT_A>, C<isPRINT_L1>, C<isPRINT_uvchr>, C<isPRINT_utf8>,
998 C<isPRINT_utf8_safe>, C<isPRINT_LC>, C<isPRINT_LC_uvchr>, C<isPRINT_LC_utf8>,
999 and C<isPRINT_LC_utf8_safe>.
1000
1001 =for apidoc Amh|bool|isPRINT_A|int ch
1002 =for apidoc Amh|bool|isPRINT_L1|int ch
1003 =for apidoc Amh|bool|isPRINT_uvchr|int ch
1004 =for apidoc Amh|bool|isPRINT_utf8_safe|U8 * s|U8 * end
1005 =for apidoc Amh|bool|isPRINT_utf8|U8 * s|U8 * end
1006 =for apidoc Amh|bool|isPRINT_LC|int ch
1007 =for apidoc Amh|bool|isPRINT_LC_uvchr|int ch
1008 =for apidoc Amh|bool|isPRINT_LC_utf8_safe|U8 * s| U8 *end
1009
1010 =for apidoc Am|bool|isWORDCHAR|char ch
1011 Returns a boolean indicating whether the specified character is a character
1012 that is a word character, analogous to what C<m/\w/> and C<m/[[:word:]]/> match
1013 in a regular expression.  A word character is an alphabetic character, a
1014 decimal digit, a connecting punctuation character (such as an underscore), or
1015 a "mark" character that attaches to one of those (like some sort of accent).
1016 C<isALNUM()> is a synonym provided for backward compatibility, even though a
1017 word character includes more than the standard C language meaning of
1018 alphanumeric.
1019 See the L<top of this section|/Character classification> for an explanation of
1020 variants C<isWORDCHAR_A>, C<isWORDCHAR_L1>, C<isWORDCHAR_uvchr>,
1021 C<isWORDCHAR_utf8>, and C<isWORDCHAR_utf8_safe>.  C<isWORDCHAR_LC>,
1022 C<isWORDCHAR_LC_uvchr>, C<isWORDCHAR_LC_utf8>, and C<isWORDCHAR_LC_utf8_safe>
1023 are also as described there, but additionally include the platform's native
1024 underscore.
1025
1026 =for apidoc Amh|bool|isWORDCHAR_A|int ch
1027 =for apidoc Amh|bool|isWORDCHAR_L1|int ch
1028 =for apidoc Amh|bool|isWORDCHAR_uvchr|int ch
1029 =for apidoc Amh|bool|isWORDCHAR_utf8_safe|U8 * s|U8 * end
1030 =for apidoc Amh|bool|isWORDCHAR_utf8|U8 * s|U8 * end
1031 =for apidoc Amh|bool|isWORDCHAR_LC|int ch
1032 =for apidoc Amh|bool|isWORDCHAR_LC_uvchr|int ch
1033 =for apidoc Amh|bool|isWORDCHAR_LC_utf8_safe|U8 * s| U8 *end
1034 =for apidoc Amh|bool|isALNUM|int ch
1035 =for apidoc Amh|bool|isALNUM_A|int ch
1036 =for apidoc Amh|bool|isALNUM_LC|int ch
1037 =for apidoc Amh|bool|isALNUM_LC_uvchr|int ch
1038
1039 =for apidoc Am|bool|isXDIGIT|char ch
1040 Returns a boolean indicating whether the specified character is a hexadecimal
1041 digit.  In the ASCII range these are C<[0-9A-Fa-f]>.  Variants C<isXDIGIT_A()>
1042 and C<isXDIGIT_L1()> are identical to C<isXDIGIT()>.
1043 See the L<top of this section|/Character classification> for an explanation of
1044 variants
1045 C<isXDIGIT_uvchr>, C<isXDIGIT_utf8>, C<isXDIGIT_utf8_safe>, C<isXDIGIT_LC>,
1046 C<isXDIGIT_LC_uvchr>, C<isXDIGIT_LC_utf8>, and C<isXDIGIT_LC_utf8_safe>.
1047
1048 =for apidoc Amh|bool|isXDIGIT_A|int ch
1049 =for apidoc Amh|bool|isXDIGIT_L1|int ch
1050 =for apidoc Amh|bool|isXDIGIT_uvchr|int ch
1051 =for apidoc Amh|bool|isXDIGIT_utf8_safe|U8 * s|U8 * end
1052 =for apidoc Amh|bool|isXDIGIT_utf8|U8 * s|U8 * end
1053 =for apidoc Amh|bool|isXDIGIT_LC|int ch
1054 =for apidoc Amh|bool|isXDIGIT_LC_uvchr|int ch
1055 =for apidoc Amh|bool|isXDIGIT_LC_utf8_safe|U8 * s| U8 *end
1056
1057 =for apidoc Am|bool|isIDFIRST|char ch
1058 Returns a boolean indicating whether the specified character can be the first
1059 character of an identifier.  This is very close to, but not quite the same as
1060 the official Unicode property C<XID_Start>.  The difference is that this
1061 returns true only if the input character also matches L</isWORDCHAR>.
1062 See the L<top of this section|/Character classification> for an explanation of
1063 variants
1064 C<isIDFIRST_A>, C<isIDFIRST_L1>, C<isIDFIRST_uvchr>, C<isIDFIRST_utf8>,
1065 C<isIDFIRST_utf8_safe>, C<isIDFIRST_LC>, C<isIDFIRST_LC_uvchr>,
1066 C<isIDFIRST_LC_utf8>, and C<isIDFIRST_LC_utf8_safe>.
1067
1068 =for apidoc Amh|bool|isIDFIRST_A|int ch
1069 =for apidoc Amh|bool|isIDFIRST_L1|int ch
1070 =for apidoc Amh|bool|isIDFIRST_uvchr|int ch
1071 =for apidoc Amh|bool|isIDFIRST_utf8_safe|U8 * s|U8 * end
1072 =for apidoc Amh|bool|isIDFIRST_utf8|U8 * s|U8 * end
1073 =for apidoc Amh|bool|isIDFIRST_LC|int ch
1074 =for apidoc Amh|bool|isIDFIRST_LC_uvchr|int ch
1075 =for apidoc Amh|bool|isIDFIRST_LC_utf8_safe|U8 * s| U8 *end
1076
1077 =for apidoc Am|bool|isIDCONT|char ch
1078 Returns a boolean indicating whether the specified character can be the
1079 second or succeeding character of an identifier.  This is very close to, but
1080 not quite the same as the official Unicode property C<XID_Continue>.  The
1081 difference is that this returns true only if the input character also matches
1082 L</isWORDCHAR>.  See the L<top of this section|/Character classification> for
1083 an explanation of variants C<isIDCONT_A>, C<isIDCONT_L1>, C<isIDCONT_uvchr>,
1084 C<isIDCONT_utf8>, C<isIDCONT_utf8_safe>, C<isIDCONT_LC>, C<isIDCONT_LC_uvchr>,
1085 C<isIDCONT_LC_utf8>, and C<isIDCONT_LC_utf8_safe>.
1086
1087 =for apidoc Amh|bool|isIDCONT_A|int ch
1088 =for apidoc Amh|bool|isIDCONT_L1|int ch
1089 =for apidoc Amh|bool|isIDCONT_uvchr|int ch
1090 =for apidoc Amh|bool|isIDCONT_utf8_safe|U8 * s|U8 * end
1091 =for apidoc Amh|bool|isIDCONT_utf8|U8 * s|U8 * end
1092 =for apidoc Amh|bool|isIDCONT_LC|int ch
1093 =for apidoc Amh|bool|isIDCONT_LC_uvchr|int ch
1094 =for apidoc Amh|bool|isIDCONT_LC_utf8_safe|U8 * s| U8 *end
1095
1096 =head1 Miscellaneous Functions
1097
1098 =for apidoc Am|U8|READ_XDIGIT|char str*
1099 Returns the value of an ASCII-range hex digit and advances the string pointer.
1100 Behaviour is only well defined when isXDIGIT(*str) is true.
1101
1102 =head1 Character case changing
1103 Perl uses "full" Unicode case mappings.  This means that converting a single
1104 character to another case may result in a sequence of more than one character.
1105 For example, the uppercase of C<E<223>> (LATIN SMALL LETTER SHARP S) is the two
1106 character sequence C<SS>.  This presents some complications   The lowercase of
1107 all characters in the range 0..255 is a single character, and thus
1108 C<L</toLOWER_L1>> is furnished.  But, C<toUPPER_L1> can't exist, as it couldn't
1109 return a valid result for all legal inputs.  Instead C<L</toUPPER_uvchr>> has
1110 an API that does allow every possible legal result to be returned.)  Likewise
1111 no other function that is crippled by not being able to give the correct
1112 results for the full range of possible inputs has been implemented here.
1113
1114 =for apidoc Am|U8|toUPPER|int ch
1115 Converts the specified character to uppercase.  If the input is anything but an
1116 ASCII lowercase character, that input character itself is returned.  Variant
1117 C<toUPPER_A> is equivalent.
1118
1119 =for apidoc Am|UV|toUPPER_uvchr|UV cp|U8* s|STRLEN* lenp
1120 Converts the code point C<cp> to its uppercase version, and
1121 stores that in UTF-8 in C<s>, and its length in bytes in C<lenp>.  The code
1122 point is interpreted as native if less than 256; otherwise as Unicode.  Note
1123 that the buffer pointed to by C<s> needs to be at least C<UTF8_MAXBYTES_CASE+1>
1124 bytes since the uppercase version may be longer than the original character.
1125
1126 The first code point of the uppercased version is returned
1127 (but note, as explained at L<the top of this section|/Character case
1128 changing>, that there may be more.)
1129
1130 =for apidoc Am|UV|toUPPER_utf8|U8* p|U8* e|U8* s|STRLEN* lenp
1131 Converts the first UTF-8 encoded character in the sequence starting at C<p> and
1132 extending no further than S<C<e - 1>> to its uppercase version, and
1133 stores that in UTF-8 in C<s>, and its length in bytes in C<lenp>.  Note
1134 that the buffer pointed to by C<s> needs to be at least C<UTF8_MAXBYTES_CASE+1>
1135 bytes since the uppercase version may be longer than the original character.
1136
1137 The first code point of the uppercased version is returned
1138 (but note, as explained at L<the top of this section|/Character case
1139 changing>, that there may be more).
1140
1141 It will not attempt to read beyond S<C<e - 1>>, provided that the constraint
1142 S<C<s E<lt> e>> is true (this is asserted for in C<-DDEBUGGING> builds).  If
1143 the UTF-8 for the input character is malformed in some way, the program may
1144 croak, or the function may return the REPLACEMENT CHARACTER, at the discretion
1145 of the implementation, and subject to change in future releases.
1146
1147 =for apidoc Am|UV|toUPPER_utf8_safe|U8* p|U8* e|U8* s|STRLEN* lenp
1148 Same as L</toUPPER_utf8>.
1149
1150 =for apidoc Am|U8|toFOLD|U8 ch
1151 Converts the specified character to foldcase.  If the input is anything but an
1152 ASCII uppercase character, that input character itself is returned.  Variant
1153 C<toFOLD_A> is equivalent.  (There is no equivalent C<to_FOLD_L1> for the full
1154 Latin1 range, as the full generality of L</toFOLD_uvchr> is needed there.)
1155
1156 =for apidoc Am|UV|toFOLD_uvchr|UV cp|U8* s|STRLEN* lenp
1157 Converts the code point C<cp> to its foldcase version, and
1158 stores that in UTF-8 in C<s>, and its length in bytes in C<lenp>.  The code
1159 point is interpreted as native if less than 256; otherwise as Unicode.  Note
1160 that the buffer pointed to by C<s> needs to be at least C<UTF8_MAXBYTES_CASE+1>
1161 bytes since the foldcase version may be longer than the original character.
1162
1163 The first code point of the foldcased version is returned
1164 (but note, as explained at L<the top of this section|/Character case
1165 changing>, that there may be more).
1166
1167 =for apidoc Am|UV|toFOLD_utf8|U8* p|U8* e|U8* s|STRLEN* lenp
1168 Converts the first UTF-8 encoded character in the sequence starting at C<p> and
1169 extending no further than S<C<e - 1>> to its foldcase version, and
1170 stores that in UTF-8 in C<s>, and its length in bytes in C<lenp>.  Note
1171 that the buffer pointed to by C<s> needs to be at least C<UTF8_MAXBYTES_CASE+1>
1172 bytes since the foldcase version may be longer than the original character.
1173
1174 The first code point of the foldcased version is returned
1175 (but note, as explained at L<the top of this section|/Character case
1176 changing>, that there may be more).
1177
1178 It will not attempt
1179 to read beyond S<C<e - 1>>, provided that the constraint S<C<s E<lt> e>> is
1180 true (this is asserted for in C<-DDEBUGGING> builds).  If the UTF-8 for the
1181 input character is malformed in some way, the program may croak, or the
1182 function may return the REPLACEMENT CHARACTER, at the discretion of the
1183 implementation, and subject to change in future releases.
1184
1185 =for apidoc Am|UV|toFOLD_utf8_safe|U8* p|U8* e|U8* s|STRLEN* lenp
1186 Same as L</toFOLD_utf8>.
1187
1188 =for apidoc Am|U8|toLOWER|U8 ch
1189 Converts the specified character to lowercase.  If the input is anything but an
1190 ASCII uppercase character, that input character itself is returned.  Variant
1191 C<toLOWER_A> is equivalent.
1192
1193 =for apidoc Am|U8|toLOWER_L1|U8 ch
1194 Converts the specified Latin1 character to lowercase.  The results are
1195 undefined if the input doesn't fit in a byte.
1196
1197 =for apidoc Am|U8|toLOWER_LC|U8 ch
1198 Converts the specified character to lowercase using the current locale's rules,
1199 if possible; otherwise returns the input character itself.
1200
1201 =for apidoc Am|UV|toLOWER_uvchr|UV cp|U8* s|STRLEN* lenp
1202 Converts the code point C<cp> to its lowercase version, and
1203 stores that in UTF-8 in C<s>, and its length in bytes in C<lenp>.  The code
1204 point is interpreted as native if less than 256; otherwise as Unicode.  Note
1205 that the buffer pointed to by C<s> needs to be at least C<UTF8_MAXBYTES_CASE+1>
1206 bytes since the lowercase version may be longer than the original character.
1207
1208 The first code point of the lowercased version is returned
1209 (but note, as explained at L<the top of this section|/Character case
1210 changing>, that there may be more).
1211
1212 =for apidoc Am|UV|toLOWER_utf8|U8* p|U8* e|U8* s|STRLEN* lenp
1213 Converts the first UTF-8 encoded character in the sequence starting at C<p> and
1214 extending no further than S<C<e - 1>> to its lowercase version, and
1215 stores that in UTF-8 in C<s>, and its length in bytes in C<lenp>.  Note
1216 that the buffer pointed to by C<s> needs to be at least C<UTF8_MAXBYTES_CASE+1>
1217 bytes since the lowercase version may be longer than the original character.
1218
1219 The first code point of the lowercased version is returned
1220 (but note, as explained at L<the top of this section|/Character case
1221 changing>, that there may be more).
1222 It will not attempt to read beyond S<C<e - 1>>, provided that the constraint
1223 S<C<s E<lt> e>> is true (this is asserted for in C<-DDEBUGGING> builds).  If
1224 the UTF-8 for the input character is malformed in some way, the program may
1225 croak, or the function may return the REPLACEMENT CHARACTER, at the discretion
1226 of the implementation, and subject to change in future releases.
1227
1228 =for apidoc Am|UV|toLOWER_utf8_safe|U8* p|U8* e|U8* s|STRLEN* lenp
1229 Same as L</toLOWER_utf8>.
1230
1231 =for apidoc Am|U8|toTITLE|U8 ch
1232 Converts the specified character to titlecase.  If the input is anything but an
1233 ASCII lowercase character, that input character itself is returned.  Variant
1234 C<toTITLE_A> is equivalent.  (There is no C<toTITLE_L1> for the full Latin1
1235 range, as the full generality of L</toTITLE_uvchr> is needed there.  Titlecase is
1236 not a concept used in locale handling, so there is no functionality for that.)
1237
1238 =for apidoc Am|UV|toTITLE_uvchr|UV cp|U8* s|STRLEN* lenp
1239 Converts the code point C<cp> to its titlecase version, and
1240 stores that in UTF-8 in C<s>, and its length in bytes in C<lenp>.  The code
1241 point is interpreted as native if less than 256; otherwise as Unicode.  Note
1242 that the buffer pointed to by C<s> needs to be at least C<UTF8_MAXBYTES_CASE+1>
1243 bytes since the titlecase version may be longer than the original character.
1244
1245 The first code point of the titlecased version is returned
1246 (but note, as explained at L<the top of this section|/Character case
1247 changing>, that there may be more).
1248
1249 =for apidoc Am|UV|toTITLE_utf8|U8* p|U8* e|U8* s|STRLEN* lenp
1250 Converts the first UTF-8 encoded character in the sequence starting at C<p> and
1251 extending no further than S<C<e - 1>> to its titlecase version, and
1252 stores that in UTF-8 in C<s>, and its length in bytes in C<lenp>.  Note
1253 that the buffer pointed to by C<s> needs to be at least C<UTF8_MAXBYTES_CASE+1>
1254 bytes since the titlecase version may be longer than the original character.
1255
1256 The first code point of the titlecased version is returned
1257 (but note, as explained at L<the top of this section|/Character case
1258 changing>, that there may be more).
1259
1260 It will not attempt
1261 to read beyond S<C<e - 1>>, provided that the constraint S<C<s E<lt> e>> is
1262 true (this is asserted for in C<-DDEBUGGING> builds).  If the UTF-8 for the
1263 input character is malformed in some way, the program may croak, or the
1264 function may return the REPLACEMENT CHARACTER, at the discretion of the
1265 implementation, and subject to change in future releases.
1266
1267 =for apidoc Am|UV|toTITLE_utf8_safe|U8* p|U8* e|U8* s|STRLEN* lenp
1268 Same as L</toTITLE_utf8>.
1269
1270 =cut
1271
1272 XXX Still undocumented isVERTWS_uvchr and _utf8; it's unclear what their names
1273 really should be.  Also toUPPER_LC and toFOLD_LC, which are subject to change,
1274 and aren't general purpose as they don't work on U+DF, and assert against that.
1275
1276 Note that these macros are repeated in Devel::PPPort, so should also be
1277 patched there.  The file as of this writing is cpan/Devel-PPPort/parts/inc/misc
1278
1279 */
1280
1281 /*
1282    void below because that's the best fit, and works for Devel::PPPort
1283 =for apidoc AmnU|void|WIDEST_UTYPE
1284
1285 Yields the widest unsigned integer type on the platform, currently either
1286 C<U32> or C<64>.  This can be used in declarations such as
1287
1288  WIDEST_UTYPE my_uv;
1289
1290 or casts
1291
1292  my_uv = (WIDEST_UTYPE) val;
1293
1294 =cut
1295
1296 */
1297 #ifdef QUADKIND
1298 #   define WIDEST_UTYPE U64
1299 #else
1300 #   define WIDEST_UTYPE U32
1301 #endif
1302
1303 /* FITS_IN_8_BITS(c) returns true if c doesn't have  a bit set other than in
1304  * the lower 8.  It is designed to be hopefully bomb-proof, making sure that no
1305  * bits of information are lost even on a 64-bit machine, but to get the
1306  * compiler to optimize it out if possible.  This is because Configure makes
1307  * sure that the machine has an 8-bit byte, so if c is stored in a byte, the
1308  * sizeof() guarantees that this evaluates to a constant true at compile time.
1309  *
1310  * For Coverity, be always true, because otherwise Coverity thinks
1311  * it finds several expressions that are always true, independent
1312  * of operands.  Well, they are, but that is kind of the point.
1313  */
1314 #ifndef __COVERITY__
1315   /* The '| 0' part ensures a compiler error if c is not integer (like e.g., a
1316    * pointer) */
1317 #define FITS_IN_8_BITS(c) (   (sizeof(c) == 1)                      \
1318                            || !(((WIDEST_UTYPE)((c) | 0)) & ~0xFF))
1319 #else
1320 #define FITS_IN_8_BITS(c) (1)
1321 #endif
1322
1323 /* Returns true if l <= c <= (l + n), where 'l' and 'n' are non-negative
1324  * Written this way so that after optimization, only one conditional test is
1325  * needed.  (The NV casts stop any warnings about comparison always being true
1326  * if called with an unsigned.  The cast preserves the sign, which is all we
1327  * care about.) */
1328 #define withinCOUNT(c, l, n) (__ASSERT_((NV) (l) >= 0)                         \
1329                               __ASSERT_((NV) (n) >= 0)                         \
1330    (((WIDEST_UTYPE) (((c)) - ((l) | 0))) <= (((WIDEST_UTYPE) ((n) | 0)))))
1331
1332 /* Returns true if c is in the range l..u, where 'l' is non-negative
1333  * Written this way so that after optimization, only one conditional test is
1334  * needed. */
1335 #define inRANGE(c, l, u) (__ASSERT_((u) >= (l))                                \
1336    (  (sizeof(c) == sizeof(U8))  ? withinCOUNT(((U8)  (c)), (l), ((u) - (l)))  \
1337     : (sizeof(c) == sizeof(U32)) ? withinCOUNT(((U32) (c)), (l), ((u) - (l)))  \
1338     : (__ASSERT_(sizeof(c) == sizeof(WIDEST_UTYPE))                            \
1339                           withinCOUNT(((WIDEST_UTYPE) (c)), (l), ((u) - (l))))))
1340
1341 #ifdef EBCDIC
1342 #   ifndef _ALL_SOURCE
1343         /* The native libc isascii() et.al. functions return the wrong results
1344          * on at least z/OS unless this is defined. */
1345 #       error   _ALL_SOURCE should probably be defined
1346 #   endif
1347 #else
1348     /* There is a simple definition of ASCII for ASCII platforms.  But the
1349      * EBCDIC one isn't so simple, so is defined using table look-up like the
1350      * other macros below.
1351      *
1352      * The cast here is used instead of '(c) >= 0', because some compilers emit
1353      * a warning that that test is always true when the parameter is an
1354      * unsigned type.  khw supposes that it could be written as
1355      *      && ((c) == '\0' || (c) > 0)
1356      * to avoid the message, but the cast will likely avoid extra branches even
1357      * with stupid compilers.
1358      *
1359      * The '| 0' part ensures a compiler error if c is not integer (like e.g.,
1360      * a pointer) */
1361 #   define isASCII(c)    ((WIDEST_UTYPE)((c) | 0) < 128)
1362 #endif
1363
1364 /* Take the eight possible bit patterns of the lower 3 bits and you get the
1365  * lower 3 bits of the 8 octal digits, in both ASCII and EBCDIC, so those bits
1366  * can be ignored.  If the rest match '0', we have an octal */
1367 #define isOCTAL_A(c)  (((WIDEST_UTYPE)((c) | 0) & ~7) == '0')
1368
1369 #ifdef H_PERL       /* If have access to perl.h, lookup in its table */
1370
1371 /* Character class numbers.  For internal core Perl use only.  The ones less
1372  * than 32 are used in PL_charclass[] and the ones up through the one that
1373  * corresponds to <_HIGHEST_REGCOMP_DOT_H_SYNC> are used by regcomp.h and
1374  * related files.  PL_charclass ones use names used in l1_char_class_tab.h but
1375  * their actual definitions are here.  If that file has a name not used here,
1376  * it won't compile.
1377  *
1378  * The first group of these is ordered in what I (khw) estimate to be the
1379  * frequency of their use.  This gives a slight edge to exiting a loop earlier
1380  * (in reginclass() in regexec.c).  Except \v should be last, as it isn't a
1381  * real Posix character class, and some (small) inefficiencies in regular
1382  * expression handling would be introduced by putting it in the middle of those
1383  * that are.  Also, cntrl and ascii come after the others as it may be useful
1384  * to group these which have no members that match above Latin1, (or above
1385  * ASCII in the latter case) */
1386
1387 #  define _CC_WORDCHAR           0      /* \w and [:word:] */
1388 #  define _CC_DIGIT              1      /* \d and [:digit:] */
1389 #  define _CC_ALPHA              2      /* [:alpha:] */
1390 #  define _CC_LOWER              3      /* [:lower:] */
1391 #  define _CC_UPPER              4      /* [:upper:] */
1392 #  define _CC_PUNCT              5      /* [:punct:] */
1393 #  define _CC_PRINT              6      /* [:print:] */
1394 #  define _CC_ALPHANUMERIC       7      /* [:alnum:] */
1395 #  define _CC_GRAPH              8      /* [:graph:] */
1396 #  define _CC_CASED              9      /* [:lower:] or [:upper:] under /i */
1397 #  define _CC_SPACE             10      /* \s, [:space:] */
1398 #  define _CC_BLANK             11      /* [:blank:] */
1399 #  define _CC_XDIGIT            12      /* [:xdigit:] */
1400 #  define _CC_CNTRL             13      /* [:cntrl:] */
1401 #  define _CC_ASCII             14      /* [:ascii:] */
1402 #  define _CC_VERTSPACE         15      /* \v */
1403
1404 #  define _HIGHEST_REGCOMP_DOT_H_SYNC _CC_VERTSPACE
1405
1406 /* The members of the third group below do not need to be coordinated with data
1407  * structures in regcomp.[ch] and regexec.c. */
1408 #  define _CC_IDFIRST                  16
1409 #  define _CC_CHARNAME_CONT            17
1410 #  define _CC_NONLATIN1_FOLD           18
1411 #  define _CC_NONLATIN1_SIMPLE_FOLD    19
1412 #  define _CC_QUOTEMETA                20
1413 #  define _CC_NON_FINAL_FOLD           21
1414 #  define _CC_IS_IN_SOME_FOLD          22
1415 #  define _CC_BINDIGIT                 23
1416 #  define _CC_OCTDIGIT                 24
1417 #  define _CC_MNEMONIC_CNTRL           25
1418
1419 /* This next group is only used on EBCDIC platforms, so theoretically could be
1420  * shared with something entirely different that's only on ASCII platforms */
1421 #  define _CC_UTF8_START_BYTE_IS_FOR_AT_LEAST_SURROGATE 31
1422 /* Unused: 26-30
1423  * If more bits are needed, one could add a second word for non-64bit
1424  * QUAD_IS_INT systems, using some #ifdefs to distinguish between having a 2nd
1425  * word or not.  The IS_IN_SOME_FOLD bit is the most easily expendable, as it
1426  * is used only for optimization (as of this writing), and differs in the
1427  * Latin1 range from the ALPHA bit only in two relatively unimportant
1428  * characters: the masculine and feminine ordinal indicators, so removing it
1429  * would just cause /i regexes which match them to run less efficiently.
1430  * Similarly the EBCDIC-only bits are used just for speed, and could be
1431  * replaced by other means */
1432
1433 #if defined(PERL_CORE) || defined(PERL_EXT)
1434 /* An enum version of the character class numbers, to help compilers
1435  * optimize */
1436 typedef enum {
1437     _CC_ENUM_ALPHA          = _CC_ALPHA,
1438     _CC_ENUM_ALPHANUMERIC   = _CC_ALPHANUMERIC,
1439     _CC_ENUM_ASCII          = _CC_ASCII,
1440     _CC_ENUM_BLANK          = _CC_BLANK,
1441     _CC_ENUM_CASED          = _CC_CASED,
1442     _CC_ENUM_CNTRL          = _CC_CNTRL,
1443     _CC_ENUM_DIGIT          = _CC_DIGIT,
1444     _CC_ENUM_GRAPH          = _CC_GRAPH,
1445     _CC_ENUM_LOWER          = _CC_LOWER,
1446     _CC_ENUM_PRINT          = _CC_PRINT,
1447     _CC_ENUM_PUNCT          = _CC_PUNCT,
1448     _CC_ENUM_SPACE          = _CC_SPACE,
1449     _CC_ENUM_UPPER          = _CC_UPPER,
1450     _CC_ENUM_VERTSPACE      = _CC_VERTSPACE,
1451     _CC_ENUM_WORDCHAR       = _CC_WORDCHAR,
1452     _CC_ENUM_XDIGIT         = _CC_XDIGIT
1453 } _char_class_number;
1454 #endif
1455
1456 #define POSIX_CC_COUNT    (_HIGHEST_REGCOMP_DOT_H_SYNC + 1)
1457
1458 START_EXTERN_C
1459 #  ifdef DOINIT
1460 EXTCONST  U32 PL_charclass[] = {
1461 #    include "l1_char_class_tab.h"
1462 };
1463
1464 #  else /* ! DOINIT */
1465 EXTCONST U32 PL_charclass[];
1466 #  endif
1467 END_EXTERN_C
1468
1469     /* The 1U keeps Solaris from griping when shifting sets the uppermost bit */
1470 #   define _CC_mask(classnum) (1U << (classnum))
1471
1472     /* For internal core Perl use only: the base macro for defining macros like
1473      * isALPHA */
1474 #   define _generic_isCC(c, classnum) cBOOL(FITS_IN_8_BITS(c)    \
1475                 && (PL_charclass[(U8) (c)] & _CC_mask(classnum)))
1476
1477     /* The mask for the _A versions of the macros; it just adds in the bit for
1478      * ASCII. */
1479 #   define _CC_mask_A(classnum) (_CC_mask(classnum) | _CC_mask(_CC_ASCII))
1480
1481     /* For internal core Perl use only: the base macro for defining macros like
1482      * isALPHA_A.  The foo_A version makes sure that both the desired bit and
1483      * the ASCII bit are present */
1484 #   define _generic_isCC_A(c, classnum) (FITS_IN_8_BITS(c)      \
1485         && ((PL_charclass[(U8) (c)] & _CC_mask_A(classnum))     \
1486                                    == _CC_mask_A(classnum)))
1487
1488 /* On ASCII platforms certain classes form a single range.  It's faster to
1489  * special case these.  isDIGIT is a single range on all platforms */
1490 #   ifdef EBCDIC
1491 #     define isALPHA_A(c)  _generic_isCC_A(c, _CC_ALPHA)
1492 #     define isGRAPH_A(c)  _generic_isCC_A(c, _CC_GRAPH)
1493 #     define isLOWER_A(c)  _generic_isCC_A(c, _CC_LOWER)
1494 #     define isPRINT_A(c)  _generic_isCC_A(c, _CC_PRINT)
1495 #     define isUPPER_A(c)  _generic_isCC_A(c, _CC_UPPER)
1496 #   else
1497       /* By folding the upper and lowercase, we can use a single range */
1498 #     define isALPHA_A(c)  inRANGE((~('A' ^ 'a') & (c)), 'A', 'Z')
1499 #     define isGRAPH_A(c)  inRANGE(c, ' ' + 1, 0x7e)
1500 #     define isLOWER_A(c)  inRANGE(c, 'a', 'z')
1501 #     define isPRINT_A(c)  inRANGE(c, ' ', 0x7e)
1502 #     define isUPPER_A(c)  inRANGE(c, 'A', 'Z')
1503 #   endif
1504 #   define isALPHANUMERIC_A(c) _generic_isCC_A(c, _CC_ALPHANUMERIC)
1505 #   define isBLANK_A(c)  _generic_isCC_A(c, _CC_BLANK)
1506 #   define isCNTRL_A(c)  _generic_isCC_A(c, _CC_CNTRL)
1507 #   define isDIGIT_A(c)  inRANGE(c, '0', '9')
1508 #   define isPUNCT_A(c)  _generic_isCC_A(c, _CC_PUNCT)
1509 #   define isSPACE_A(c)  _generic_isCC_A(c, _CC_SPACE)
1510 #   define isWORDCHAR_A(c) _generic_isCC_A(c, _CC_WORDCHAR)
1511 #   define isXDIGIT_A(c)  _generic_isCC(c, _CC_XDIGIT) /* No non-ASCII xdigits
1512                                                         */
1513 #   define isIDFIRST_A(c) _generic_isCC_A(c, _CC_IDFIRST)
1514 #   define isALPHA_L1(c)  _generic_isCC(c, _CC_ALPHA)
1515 #   define isALPHANUMERIC_L1(c) _generic_isCC(c, _CC_ALPHANUMERIC)
1516 #   define isBLANK_L1(c)  _generic_isCC(c, _CC_BLANK)
1517
1518     /* continuation character for legal NAME in \N{NAME} */
1519 #   define isCHARNAME_CONT(c) _generic_isCC(c, _CC_CHARNAME_CONT)
1520
1521 #   define isCNTRL_L1(c)  _generic_isCC(c, _CC_CNTRL)
1522 #   define isGRAPH_L1(c)  _generic_isCC(c, _CC_GRAPH)
1523 #   define isLOWER_L1(c)  _generic_isCC(c, _CC_LOWER)
1524 #   define isPRINT_L1(c)  _generic_isCC(c, _CC_PRINT)
1525 #   define isPSXSPC_L1(c)  isSPACE_L1(c)
1526 #   define isPUNCT_L1(c)  _generic_isCC(c, _CC_PUNCT)
1527 #   define isSPACE_L1(c)  _generic_isCC(c, _CC_SPACE)
1528 #   define isUPPER_L1(c)  _generic_isCC(c, _CC_UPPER)
1529 #   define isWORDCHAR_L1(c) _generic_isCC(c, _CC_WORDCHAR)
1530 #   define isIDFIRST_L1(c) _generic_isCC(c, _CC_IDFIRST)
1531
1532 #   ifdef EBCDIC
1533 #       define isASCII(c) _generic_isCC(c, _CC_ASCII)
1534 #   endif
1535
1536     /* Participates in a single-character fold with a character above 255 */
1537 #   define _HAS_NONLATIN1_SIMPLE_FOLD_CLOSURE_ONLY_FOR_USE_BY_REGCOMP_DOT_C_AND_REGEXEC_DOT_C(c) ((! cBOOL(FITS_IN_8_BITS(c))) || (PL_charclass[(U8) (c)] & _CC_mask(_CC_NONLATIN1_SIMPLE_FOLD)))
1538
1539     /* Like the above, but also can be part of a multi-char fold */
1540 #   define _HAS_NONLATIN1_FOLD_CLOSURE_ONLY_FOR_USE_BY_REGCOMP_DOT_C_AND_REGEXEC_DOT_C(c) ((! cBOOL(FITS_IN_8_BITS(c))) || (PL_charclass[(U8) (c)] & _CC_mask(_CC_NONLATIN1_FOLD)))
1541
1542 #   define _isQUOTEMETA(c) _generic_isCC(c, _CC_QUOTEMETA)
1543 #   define _IS_NON_FINAL_FOLD_ONLY_FOR_USE_BY_REGCOMP_DOT_C(c) \
1544                                            _generic_isCC(c, _CC_NON_FINAL_FOLD)
1545 #   define _IS_IN_SOME_FOLD_ONLY_FOR_USE_BY_REGCOMP_DOT_C(c) \
1546                                            _generic_isCC(c, _CC_IS_IN_SOME_FOLD)
1547
1548 /* is c a control character for which we have a mnemonic? */
1549 #  if defined(PERL_CORE) || defined(PERL_EXT)
1550 #     define isMNEMONIC_CNTRL(c) _generic_isCC(c, _CC_MNEMONIC_CNTRL)
1551 #  endif
1552 #else   /* else we don't have perl.h H_PERL */
1553
1554     /* If we don't have perl.h, we are compiling a utility program.  Below we
1555      * hard-code various macro definitions that wouldn't otherwise be available
1556      * to it. Most are coded based on first principles.  These are written to
1557      * avoid EBCDIC vs. ASCII #ifdef's as much as possible. */
1558 #   define isDIGIT_A(c)  inRANGE(c, '0', '9')
1559 #   define isBLANK_A(c)  ((c) == ' ' || (c) == '\t')
1560 #   define isSPACE_A(c)  (isBLANK_A(c)                                   \
1561                           || (c) == '\n'                                 \
1562                           || (c) == '\r'                                 \
1563                           || (c) == '\v'                                 \
1564                           || (c) == '\f')
1565     /* On EBCDIC, there are gaps between 'i' and 'j'; 'r' and 's'.  Same for
1566      * uppercase.  The tests for those aren't necessary on ASCII, but hurt only
1567      * performance (if optimization isn't on), and allow the same code to be
1568      * used for both platform types */
1569 #   define isLOWER_A(c)  inRANGE((c), 'a', 'i')                         \
1570                       || inRANGE((c), 'j', 'r')                         \
1571                       || inRANGE((c), 's', 'z')
1572 #   define isUPPER_A(c)  inRANGE((c), 'A', 'I')                         \
1573                       || inRANGE((c), 'J', 'R')                         \
1574                       || inRANGE((c), 'S', 'Z')
1575 #   define isALPHA_A(c)  (isUPPER_A(c) || isLOWER_A(c))
1576 #   define isALPHANUMERIC_A(c) (isALPHA_A(c) || isDIGIT_A(c))
1577 #   define isWORDCHAR_A(c)   (isALPHANUMERIC_A(c) || (c) == '_')
1578 #   define isIDFIRST_A(c)    (isALPHA_A(c) || (c) == '_')
1579 #   define isXDIGIT_A(c) (   isDIGIT_A(c)                               \
1580                           || inRANGE((c), 'a', 'f')                     \
1581                           || inRANGE((c), 'A', 'F')
1582 #   define isPUNCT_A(c)  ((c) == '-' || (c) == '!' || (c) == '"'        \
1583                        || (c) == '#' || (c) == '$' || (c) == '%'        \
1584                        || (c) == '&' || (c) == '\'' || (c) == '('       \
1585                        || (c) == ')' || (c) == '*' || (c) == '+'        \
1586                        || (c) == ',' || (c) == '.' || (c) == '/'        \
1587                        || (c) == ':' || (c) == ';' || (c) == '<'        \
1588                        || (c) == '=' || (c) == '>' || (c) == '?'        \
1589                        || (c) == '@' || (c) == '[' || (c) == '\\'       \
1590                        || (c) == ']' || (c) == '^' || (c) == '_'        \
1591                        || (c) == '`' || (c) == '{' || (c) == '|'        \
1592                        || (c) == '}' || (c) == '~')
1593 #   define isGRAPH_A(c)  (isALPHANUMERIC_A(c) || isPUNCT_A(c))
1594 #   define isPRINT_A(c)  (isGRAPH_A(c) || (c) == ' ')
1595
1596 #   ifdef EBCDIC
1597         /* The below is accurate for the 3 EBCDIC code pages traditionally
1598          * supported by perl.  The only difference between them in the controls
1599          * is the position of \n, and that is represented symbolically below */
1600 #       define isCNTRL_A(c)  ((c) == '\0' || (c) == '\a' || (c) == '\b'     \
1601                           ||  (c) == '\f' || (c) == '\n' || (c) == '\r'     \
1602                           ||  (c) == '\t' || (c) == '\v'                    \
1603                           || inRANGE((c), 1, 3)     /* SOH, STX, ETX */     \
1604                           ||  (c) == 7F   /* U+7F DEL */                    \
1605                           || inRANGE((c), 0x0E, 0x13) /* SO SI DLE          \
1606                                                          DC[1-3] */         \
1607                           ||  (c) == 0x18 /* U+18 CAN */                    \
1608                           ||  (c) == 0x19 /* U+19 EOM */                    \
1609                           || inRANGE((c), 0x1C, 0x1F) /* [FGRU]S */         \
1610                           ||  (c) == 0x26 /* U+17 ETB */                    \
1611                           ||  (c) == 0x27 /* U+1B ESC */                    \
1612                           ||  (c) == 0x2D /* U+05 ENQ */                    \
1613                           ||  (c) == 0x2E /* U+06 ACK */                    \
1614                           ||  (c) == 0x32 /* U+16 SYN */                    \
1615                           ||  (c) == 0x37 /* U+04 EOT */                    \
1616                           ||  (c) == 0x3C /* U+14 DC4 */                    \
1617                           ||  (c) == 0x3D /* U+15 NAK */                    \
1618                           ||  (c) == 0x3F)/* U+1A SUB */
1619 #       define isASCII(c)    (isCNTRL_A(c) || isPRINT_A(c))
1620 #   else /* isASCII is already defined for ASCII platforms, so can use that to
1621             define isCNTRL */
1622 #       define isCNTRL_A(c)  (isASCII(c) && ! isPRINT_A(c))
1623 #   endif
1624
1625     /* The _L1 macros may be unnecessary for the utilities; I (khw) added them
1626      * during debugging, and it seems best to keep them.  We may be called
1627      * without NATIVE_TO_LATIN1 being defined.  On ASCII platforms, it doesn't
1628      * do anything anyway, so make it not a problem */
1629 #   if ! defined(EBCDIC) && ! defined(NATIVE_TO_LATIN1)
1630 #       define NATIVE_TO_LATIN1(ch) (ch)
1631 #   endif
1632 #   define isALPHA_L1(c)     (isUPPER_L1(c) || isLOWER_L1(c))
1633 #   define isALPHANUMERIC_L1(c) (isALPHA_L1(c) || isDIGIT_A(c))
1634 #   define isBLANK_L1(c)     (isBLANK_A(c)                                   \
1635                               || (FITS_IN_8_BITS(c)                          \
1636                                   && NATIVE_TO_LATIN1((U8) c) == 0xA0))
1637 #   define isCNTRL_L1(c)     (FITS_IN_8_BITS(c) && (! isPRINT_L1(c)))
1638 #   define isGRAPH_L1(c)     (isPRINT_L1(c) && (! isBLANK_L1(c)))
1639 #   define isLOWER_L1(c)     (isLOWER_A(c)                                   \
1640                               || (FITS_IN_8_BITS(c)                          \
1641                                   && ((   NATIVE_TO_LATIN1((U8) c) >= 0xDF   \
1642                                        && NATIVE_TO_LATIN1((U8) c) != 0xF7)  \
1643                                        || NATIVE_TO_LATIN1((U8) c) == 0xAA   \
1644                                        || NATIVE_TO_LATIN1((U8) c) == 0xBA   \
1645                                        || NATIVE_TO_LATIN1((U8) c) == 0xB5)))
1646 #   define isPRINT_L1(c)     (isPRINT_A(c)                                   \
1647                               || (FITS_IN_8_BITS(c)                          \
1648                                   && NATIVE_TO_LATIN1((U8) c) >= 0xA0))
1649 #   define isPUNCT_L1(c)     (isPUNCT_A(c)                                   \
1650                               || (FITS_IN_8_BITS(c)                          \
1651                                   && (   NATIVE_TO_LATIN1((U8) c) == 0xA1    \
1652                                       || NATIVE_TO_LATIN1((U8) c) == 0xA7    \
1653                                       || NATIVE_TO_LATIN1((U8) c) == 0xAB    \
1654                                       || NATIVE_TO_LATIN1((U8) c) == 0xB6    \
1655                                       || NATIVE_TO_LATIN1((U8) c) == 0xB7    \
1656                                       || NATIVE_TO_LATIN1((U8) c) == 0xBB    \
1657                                       || NATIVE_TO_LATIN1((U8) c) == 0xBF)))
1658 #   define isSPACE_L1(c)     (isSPACE_A(c)                                   \
1659                               || (FITS_IN_8_BITS(c)                          \
1660                                   && (   NATIVE_TO_LATIN1((U8) c) == 0x85    \
1661                                       || NATIVE_TO_LATIN1((U8) c) == 0xA0)))
1662 #   define isUPPER_L1(c)     (isUPPER_A(c)                                   \
1663                               || (FITS_IN_8_BITS(c)                          \
1664                                   && (   IN_RANGE(NATIVE_TO_LATIN1((U8) c),  \
1665                                                   0xC0, 0xDE)                \
1666                                       && NATIVE_TO_LATIN1((U8) c) != 0xD7)))
1667 #   define isWORDCHAR_L1(c)  (isIDFIRST_L1(c) || isDIGIT_A(c))
1668 #   define isIDFIRST_L1(c)   (isALPHA_L1(c) || NATIVE_TO_LATIN1(c) == '_')
1669 #   define isCHARNAME_CONT(c) (isWORDCHAR_L1(c)                              \
1670                                || isBLANK_L1(c)                              \
1671                                || (c) == '-'                                 \
1672                                || (c) == '('                                 \
1673                                || (c) == ')')
1674     /* The following are not fully accurate in the above-ASCII range.  I (khw)
1675      * don't think it's necessary to be so for the purposes where this gets
1676      * compiled */
1677 #   define _isQUOTEMETA(c)      (FITS_IN_8_BITS(c) && ! isWORDCHAR_L1(c))
1678 #   define _IS_IN_SOME_FOLD_ONLY_FOR_USE_BY_REGCOMP_DOT_C(c) isALPHA_L1(c)
1679
1680     /*  And these aren't accurate at all.  They are useful only for above
1681      *  Latin1, which utilities and bootstrapping don't deal with */
1682 #   define _IS_NON_FINAL_FOLD_ONLY_FOR_USE_BY_REGCOMP_DOT_C(c) 0
1683 #   define _HAS_NONLATIN1_SIMPLE_FOLD_CLOSURE_ONLY_FOR_USE_BY_REGCOMP_DOT_C_AND_REGEXEC_DOT_C(c) 0
1684 #   define _HAS_NONLATIN1_FOLD_CLOSURE_ONLY_FOR_USE_BY_REGCOMP_DOT_C_AND_REGEXEC_DOT_C(c) 0
1685
1686     /* Many of the macros later in this file are defined in terms of these.  By
1687      * implementing them with a function, which converts the class number into
1688      * a call to the desired macro, all of the later ones work.  However, that
1689      * function won't be actually defined when building a utility program (no
1690      * perl.h), and so a compiler error will be generated if one is attempted
1691      * to be used.  And the above-Latin1 code points require Unicode tables to
1692      * be present, something unlikely to be the case when bootstrapping */
1693 #   define _generic_isCC(c, classnum)                                        \
1694          (FITS_IN_8_BITS(c) && S_bootstrap_ctype((U8) (c), (classnum), TRUE))
1695 #   define _generic_isCC_A(c, classnum)                                      \
1696          (FITS_IN_8_BITS(c) && S_bootstrap_ctype((U8) (c), (classnum), FALSE))
1697 #endif  /* End of no perl.h H_PERL */
1698
1699 #define isALPHANUMERIC(c)  isALPHANUMERIC_A(c)
1700 #define isALPHA(c)   isALPHA_A(c)
1701 #define isASCII_A(c)  isASCII(c)
1702 #define isASCII_L1(c)  isASCII(c)
1703 #define isBLANK(c)   isBLANK_A(c)
1704 #define isCNTRL(c)   isCNTRL_A(c)
1705 #define isDIGIT(c)   isDIGIT_A(c)
1706 #define isGRAPH(c)   isGRAPH_A(c)
1707 #define isIDFIRST(c) isIDFIRST_A(c)
1708 #define isLOWER(c)   isLOWER_A(c)
1709 #define isPRINT(c)   isPRINT_A(c)
1710 #define isPSXSPC_A(c) isSPACE_A(c)
1711 #define isPSXSPC(c)  isPSXSPC_A(c)
1712 #define isPSXSPC_L1(c) isSPACE_L1(c)
1713 #define isPUNCT(c)   isPUNCT_A(c)
1714 #define isSPACE(c)   isSPACE_A(c)
1715 #define isUPPER(c)   isUPPER_A(c)
1716 #define isWORDCHAR(c) isWORDCHAR_A(c)
1717 #define isXDIGIT(c)  isXDIGIT_A(c)
1718
1719 /* ASCII casing.  These could also be written as
1720     #define toLOWER(c) (isASCII(c) ? toLOWER_LATIN1(c) : (c))
1721     #define toUPPER(c) (isASCII(c) ? toUPPER_LATIN1_MOD(c) : (c))
1722    which uses table lookup and mask instead of subtraction.  (This would
1723    work because the _MOD does not apply in the ASCII range).
1724
1725    These actually are UTF-8 invariant casing, not just ASCII, as any non-ASCII
1726    UTF-8 invariants are neither upper nor lower.  (Only on EBCDIC platforms are
1727    there non-ASCII invariants, and all of them are controls.) */
1728 #define toLOWER(c)  (isUPPER(c) ? (U8)((c) + ('a' - 'A')) : (c))
1729 #define toUPPER(c)  (isLOWER(c) ? (U8)((c) - ('a' - 'A')) : (c))
1730
1731 /* In the ASCII range, these are equivalent to what they're here defined to be.
1732  * But by creating these definitions, other code doesn't have to be aware of
1733  * this detail.  Actually this works for all UTF-8 invariants, not just the
1734  * ASCII range. (EBCDIC platforms can have non-ASCII invariants.) */
1735 #define toFOLD(c)    toLOWER(c)
1736 #define toTITLE(c)   toUPPER(c)
1737
1738 #define toLOWER_A(c) toLOWER(c)
1739 #define toUPPER_A(c) toUPPER(c)
1740 #define toFOLD_A(c)  toFOLD(c)
1741 #define toTITLE_A(c) toTITLE(c)
1742
1743 /* Use table lookup for speed; returns the input itself if is out-of-range */
1744 #define toLOWER_LATIN1(c)    ((! FITS_IN_8_BITS(c))                        \
1745                              ? (c)                                         \
1746                              : PL_latin1_lc[ (U8) (c) ])
1747 #define toLOWER_L1(c)    toLOWER_LATIN1(c)  /* Synonym for consistency */
1748
1749 /* Modified uc.  Is correct uc except for three non-ascii chars which are
1750  * all mapped to one of them, and these need special handling; returns the
1751  * input itself if is out-of-range */
1752 #define toUPPER_LATIN1_MOD(c) ((! FITS_IN_8_BITS(c))                       \
1753                                ? (c)                                       \
1754                                : PL_mod_latin1_uc[ (U8) (c) ])
1755 #define IN_UTF8_CTYPE_LOCALE PL_in_utf8_CTYPE_locale
1756
1757 /* Use foo_LC_uvchr() instead  of these for beyond the Latin1 range */
1758
1759 /* For internal core Perl use only: the base macro for defining macros like
1760  * isALPHA_LC, which uses the current LC_CTYPE locale.  'c' is the code point
1761  * (0-255) to check.  In a UTF-8 locale, the result is the same as calling
1762  * isFOO_L1(); the 'utf8_locale_classnum' parameter is something like
1763  * _CC_UPPER, which gives the class number for doing this.  For non-UTF-8
1764  * locales, the code to actually do the test this is passed in 'non_utf8'.  If
1765  * 'c' is above 255, 0 is returned.  For accessing the full range of possible
1766  * code points under locale rules, use the macros based on _generic_LC_uvchr
1767  * instead of this. */
1768 #define _generic_LC_base(c, utf8_locale_classnum, non_utf8)                    \
1769            (! FITS_IN_8_BITS(c)                                                \
1770            ? 0                                                                 \
1771            : IN_UTF8_CTYPE_LOCALE                                              \
1772              ? cBOOL(PL_charclass[(U8) (c)] & _CC_mask(utf8_locale_classnum))  \
1773              : cBOOL(non_utf8))
1774
1775 /* For internal core Perl use only: a helper macro for defining macros like
1776  * isALPHA_LC.  'c' is the code point (0-255) to check.  The function name to
1777  * actually do this test is passed in 'non_utf8_func', which is called on 'c',
1778  * casting 'c' to the macro _LC_CAST, which should not be parenthesized.  See
1779  * _generic_LC_base for more info */
1780 #define _generic_LC(c, utf8_locale_classnum, non_utf8_func)                    \
1781                         _generic_LC_base(c,utf8_locale_classnum,               \
1782                                          non_utf8_func( (_LC_CAST) (c)))
1783
1784 /* For internal core Perl use only: like _generic_LC, but also returns TRUE if
1785  * 'c' is the platform's native underscore character */
1786 #define _generic_LC_underscore(c,utf8_locale_classnum,non_utf8_func)           \
1787                         _generic_LC_base(c, utf8_locale_classnum,              \
1788                                          (non_utf8_func( (_LC_CAST) (c))       \
1789                                           || (char)(c) == '_'))
1790
1791 /* These next three are also for internal core Perl use only: case-change
1792  * helper macros.  The reason for using the PL_latin arrays is in case the
1793  * system function is defective; it ensures uniform results that conform to the
1794  * Unicod standard.   It does not handle the anomalies in UTF-8 Turkic locales */
1795 #define _generic_toLOWER_LC(c, function, cast)  (! FITS_IN_8_BITS(c)           \
1796                                                 ? (c)                          \
1797                                                 : (IN_UTF8_CTYPE_LOCALE)       \
1798                                                   ? PL_latin1_lc[ (U8) (c) ]   \
1799                                                   : (cast)function((cast)(c)))
1800
1801 /* Note that the result can be larger than a byte in a UTF-8 locale.  It
1802  * returns a single value, so can't adequately return the upper case of LATIN
1803  * SMALL LETTER SHARP S in a UTF-8 locale (which should be a string of two
1804  * values "SS");  instead it asserts against that under DEBUGGING, and
1805  * otherwise returns its input.  It does not handle the anomalies in UTF-8
1806  * Turkic locales. */
1807 #define _generic_toUPPER_LC(c, function, cast)                                 \
1808                     (! FITS_IN_8_BITS(c)                                       \
1809                     ? (c)                                                      \
1810                     : ((! IN_UTF8_CTYPE_LOCALE)                                \
1811                       ? (cast)function((cast)(c))                              \
1812                       : ((((U8)(c)) == MICRO_SIGN)                             \
1813                         ? GREEK_CAPITAL_LETTER_MU                              \
1814                         : ((((U8)(c)) == LATIN_SMALL_LETTER_Y_WITH_DIAERESIS)  \
1815                           ? LATIN_CAPITAL_LETTER_Y_WITH_DIAERESIS              \
1816                           : ((((U8)(c)) == LATIN_SMALL_LETTER_SHARP_S)         \
1817                             ? (__ASSERT_(0) (c))                               \
1818                             : PL_mod_latin1_uc[ (U8) (c) ])))))
1819
1820 /* Note that the result can be larger than a byte in a UTF-8 locale.  It
1821  * returns a single value, so can't adequately return the fold case of LATIN
1822  * SMALL LETTER SHARP S in a UTF-8 locale (which should be a string of two
1823  * values "ss"); instead it asserts against that under DEBUGGING, and
1824  * otherwise returns its input.  It does not handle the anomalies in UTF-8
1825  * Turkic locales */
1826 #define _generic_toFOLD_LC(c, function, cast)                                  \
1827                     ((UNLIKELY((c) == MICRO_SIGN) && IN_UTF8_CTYPE_LOCALE)     \
1828                       ? GREEK_SMALL_LETTER_MU                                  \
1829                       : (__ASSERT_(! IN_UTF8_CTYPE_LOCALE                      \
1830                                    || (c) != LATIN_SMALL_LETTER_SHARP_S)       \
1831                          _generic_toLOWER_LC(c, function, cast)))
1832
1833 /* Use the libc versions for these if available. */
1834 #if defined(HAS_ISASCII)
1835 #   define isASCII_LC(c) (FITS_IN_8_BITS(c) && isascii( (U8) (c)))
1836 #else
1837 #   define isASCII_LC(c) isASCII(c)
1838 #endif
1839
1840 #if defined(HAS_ISBLANK)
1841 #   define isBLANK_LC(c) _generic_LC(c, _CC_BLANK, isblank)
1842 #else /* Unlike isASCII, varies if in a UTF-8 locale */
1843 #   define isBLANK_LC(c) ((IN_UTF8_CTYPE_LOCALE) ? isBLANK_L1(c) : isBLANK(c))
1844 #endif
1845
1846 #define _LC_CAST U8
1847
1848 #ifdef WIN32
1849     /* The Windows functions don't bother to follow the POSIX standard, which
1850      * for example says that something can't both be a printable and a control.
1851      * But Windows treats the \t control as a printable, and does such things
1852      * as making superscripts into both digits and punctuation.  This tames
1853      * these flaws by assuming that the definitions of both controls and space
1854      * are correct, and then making sure that other definitions don't have
1855      * weirdnesses, by making sure that isalnum() isn't also ispunct(), etc.
1856      * Not all possible weirdnesses are checked for, just the ones that were
1857      * detected on actual Microsoft code pages */
1858
1859 #  define isCNTRL_LC(c)  _generic_LC(c, _CC_CNTRL, iscntrl)
1860 #  define isSPACE_LC(c)  _generic_LC(c, _CC_SPACE, isspace)
1861
1862 #  define isALPHA_LC(c)  (_generic_LC(c, _CC_ALPHA, isalpha)                  \
1863                                                     && isALPHANUMERIC_LC(c))
1864 #  define isALPHANUMERIC_LC(c)  (_generic_LC(c, _CC_ALPHANUMERIC, isalnum) && \
1865                                                               ! isPUNCT_LC(c))
1866 #  define isDIGIT_LC(c)  (_generic_LC(c, _CC_DIGIT, isdigit) &&               \
1867                                                          isALPHANUMERIC_LC(c))
1868 #  define isGRAPH_LC(c)  (_generic_LC(c, _CC_GRAPH, isgraph) && isPRINT_LC(c))
1869 #  define isIDFIRST_LC(c) (((c) == '_')                                       \
1870                  || (_generic_LC(c, _CC_IDFIRST, isalpha) && ! isPUNCT_LC(c)))
1871 #  define isLOWER_LC(c)  (_generic_LC(c, _CC_LOWER, islower) && isALPHA_LC(c))
1872 #  define isPRINT_LC(c)  (_generic_LC(c, _CC_PRINT, isprint) && ! isCNTRL_LC(c))
1873 #  define isPUNCT_LC(c)  (_generic_LC(c, _CC_PUNCT, ispunct) && ! isCNTRL_LC(c))
1874 #  define isUPPER_LC(c)  (_generic_LC(c, _CC_UPPER, isupper) && isALPHA_LC(c))
1875 #  define isWORDCHAR_LC(c) (((c) == '_') || isALPHANUMERIC_LC(c))
1876 #  define isXDIGIT_LC(c) (_generic_LC(c, _CC_XDIGIT, isxdigit)                \
1877                                                     && isALPHANUMERIC_LC(c))
1878
1879 #  define toLOWER_LC(c) _generic_toLOWER_LC((c), tolower, U8)
1880 #  define toUPPER_LC(c) _generic_toUPPER_LC((c), toupper, U8)
1881 #  define toFOLD_LC(c)  _generic_toFOLD_LC((c), tolower, U8)
1882
1883 #elif defined(CTYPE256) || (!defined(isascii) && !defined(HAS_ISASCII))
1884     /* For most other platforms */
1885
1886 #  define isALPHA_LC(c)   _generic_LC(c, _CC_ALPHA, isalpha)
1887 #  define isALPHANUMERIC_LC(c)  _generic_LC(c, _CC_ALPHANUMERIC, isalnum)
1888 #  define isCNTRL_LC(c)    _generic_LC(c, _CC_CNTRL, iscntrl)
1889 #  define isDIGIT_LC(c)    _generic_LC(c, _CC_DIGIT, isdigit)
1890 #  define isGRAPH_LC(c)    _generic_LC(c, _CC_GRAPH, isgraph)
1891 #  define isIDFIRST_LC(c)  _generic_LC_underscore(c, _CC_IDFIRST, isalpha)
1892 #  define isLOWER_LC(c)    _generic_LC(c, _CC_LOWER, islower)
1893 #  define isPRINT_LC(c)    _generic_LC(c, _CC_PRINT, isprint)
1894 #  define isPUNCT_LC(c)    _generic_LC(c, _CC_PUNCT, ispunct)
1895 #  define isSPACE_LC(c)    _generic_LC(c, _CC_SPACE, isspace)
1896 #  define isUPPER_LC(c)    _generic_LC(c, _CC_UPPER, isupper)
1897 #  define isWORDCHAR_LC(c) _generic_LC_underscore(c, _CC_WORDCHAR, isalnum)
1898 #  define isXDIGIT_LC(c)   _generic_LC(c, _CC_XDIGIT, isxdigit)
1899
1900
1901 #  define toLOWER_LC(c) _generic_toLOWER_LC((c), tolower, U8)
1902 #  define toUPPER_LC(c) _generic_toUPPER_LC((c), toupper, U8)
1903 #  define toFOLD_LC(c)  _generic_toFOLD_LC((c), tolower, U8)
1904
1905 #else  /* The final fallback position */
1906
1907 #  define isALPHA_LC(c)         (isascii(c) && isalpha(c))
1908 #  define isALPHANUMERIC_LC(c)  (isascii(c) && isalnum(c))
1909 #  define isCNTRL_LC(c)         (isascii(c) && iscntrl(c))
1910 #  define isDIGIT_LC(c)         (isascii(c) && isdigit(c))
1911 #  define isGRAPH_LC(c)         (isascii(c) && isgraph(c))
1912 #  define isIDFIRST_LC(c)       (isascii(c) && (isalpha(c) || (c) == '_'))
1913 #  define isLOWER_LC(c)         (isascii(c) && islower(c))
1914 #  define isPRINT_LC(c)         (isascii(c) && isprint(c))
1915 #  define isPUNCT_LC(c)         (isascii(c) && ispunct(c))
1916 #  define isSPACE_LC(c)         (isascii(c) && isspace(c))
1917 #  define isUPPER_LC(c)         (isascii(c) && isupper(c))
1918 #  define isWORDCHAR_LC(c)      (isascii(c) && (isalnum(c) || (c) == '_'))
1919 #  define isXDIGIT_LC(c)        (isascii(c) && isxdigit(c))
1920
1921 #  define toLOWER_LC(c) (isascii(c) ? tolower(c) : (c))
1922 #  define toUPPER_LC(c) (isascii(c) ? toupper(c) : (c))
1923 #  define toFOLD_LC(c)  (isascii(c) ? tolower(c) : (c))
1924
1925 #endif
1926
1927 #define isIDCONT(c)             isWORDCHAR(c)
1928 #define isIDCONT_A(c)           isWORDCHAR_A(c)
1929 #define isIDCONT_L1(c)          isWORDCHAR_L1(c)
1930 #define isIDCONT_LC(c)          isWORDCHAR_LC(c)
1931 #define isPSXSPC_LC(c)          isSPACE_LC(c)
1932
1933 /* For internal core Perl use only: the base macros for defining macros like
1934  * isALPHA_uvchr.  'c' is the code point to check.  'classnum' is the POSIX class
1935  * number defined earlier in this file.  _generic_uvchr() is used for POSIX
1936  * classes where there is a macro or function 'above_latin1' that takes the
1937  * single argument 'c' and returns the desired value.  These exist for those
1938  * classes which have simple definitions, avoiding the overhead of an inversion
1939  * list binary search.  _generic_invlist_uvchr() can be used
1940  * for classes where that overhead is faster than a direct lookup.
1941  * _generic_uvchr() won't compile if 'c' isn't unsigned, as it won't match the
1942  * 'above_latin1' prototype. _generic_isCC() macro does bounds checking, so
1943  * have duplicate checks here, so could create versions of the macros that
1944  * don't, but experiments show that gcc optimizes them out anyway. */
1945
1946 /* Note that all ignore 'use bytes' */
1947 #define _generic_uvchr(classnum, above_latin1, c) ((c) < 256                \
1948                                              ? _generic_isCC(c, classnum)   \
1949                                              : above_latin1(c))
1950 #define _generic_invlist_uvchr(classnum, c) ((c) < 256                        \
1951                                              ? _generic_isCC(c, classnum)   \
1952                                              : _is_uni_FOO(classnum, c))
1953 #define isALPHA_uvchr(c)      _generic_invlist_uvchr(_CC_ALPHA, c)
1954 #define isALPHANUMERIC_uvchr(c) _generic_invlist_uvchr(_CC_ALPHANUMERIC, c)
1955 #define isASCII_uvchr(c)      isASCII(c)
1956 #define isBLANK_uvchr(c)      _generic_uvchr(_CC_BLANK, is_HORIZWS_cp_high, c)
1957 #define isCNTRL_uvchr(c)      isCNTRL_L1(c) /* All controls are in Latin1 */
1958 #define isDIGIT_uvchr(c)      _generic_invlist_uvchr(_CC_DIGIT, c)
1959 #define isGRAPH_uvchr(c)      _generic_invlist_uvchr(_CC_GRAPH, c)
1960 #define isIDCONT_uvchr(c)                                                   \
1961                     _generic_uvchr(_CC_WORDCHAR, _is_uni_perl_idcont, c)
1962 #define isIDFIRST_uvchr(c)                                                  \
1963                     _generic_uvchr(_CC_IDFIRST, _is_uni_perl_idstart, c)
1964 #define isLOWER_uvchr(c)      _generic_invlist_uvchr(_CC_LOWER, c)
1965 #define isPRINT_uvchr(c)      _generic_invlist_uvchr(_CC_PRINT, c)
1966
1967 #define isPUNCT_uvchr(c)      _generic_invlist_uvchr(_CC_PUNCT, c)
1968 #define isSPACE_uvchr(c)      _generic_uvchr(_CC_SPACE, is_XPERLSPACE_cp_high, c)
1969 #define isPSXSPC_uvchr(c)     isSPACE_uvchr(c)
1970
1971 #define isUPPER_uvchr(c)      _generic_invlist_uvchr(_CC_UPPER, c)
1972 #define isVERTWS_uvchr(c)     _generic_uvchr(_CC_VERTSPACE, is_VERTWS_cp_high, c)
1973 #define isWORDCHAR_uvchr(c)   _generic_invlist_uvchr(_CC_WORDCHAR, c)
1974 #define isXDIGIT_uvchr(c)     _generic_uvchr(_CC_XDIGIT, is_XDIGIT_cp_high, c)
1975
1976 #define toFOLD_uvchr(c,s,l)     to_uni_fold(c,s,l)
1977 #define toLOWER_uvchr(c,s,l)    to_uni_lower(c,s,l)
1978 #define toTITLE_uvchr(c,s,l)    to_uni_title(c,s,l)
1979 #define toUPPER_uvchr(c,s,l)    to_uni_upper(c,s,l)
1980
1981 /* For backwards compatibility, even though '_uni' should mean official Unicode
1982  * code points, in Perl it means native for those below 256 */
1983 #define isALPHA_uni(c)          isALPHA_uvchr(c)
1984 #define isALPHANUMERIC_uni(c)   isALPHANUMERIC_uvchr(c)
1985 #define isASCII_uni(c)          isASCII_uvchr(c)
1986 #define isBLANK_uni(c)          isBLANK_uvchr(c)
1987 #define isCNTRL_uni(c)          isCNTRL_uvchr(c)
1988 #define isDIGIT_uni(c)          isDIGIT_uvchr(c)
1989 #define isGRAPH_uni(c)          isGRAPH_uvchr(c)
1990 #define isIDCONT_uni(c)         isIDCONT_uvchr(c)
1991 #define isIDFIRST_uni(c)        isIDFIRST_uvchr(c)
1992 #define isLOWER_uni(c)          isLOWER_uvchr(c)
1993 #define isPRINT_uni(c)          isPRINT_uvchr(c)
1994 #define isPUNCT_uni(c)          isPUNCT_uvchr(c)
1995 #define isSPACE_uni(c)          isSPACE_uvchr(c)
1996 #define isPSXSPC_uni(c)         isPSXSPC_uvchr(c)
1997 #define isUPPER_uni(c)          isUPPER_uvchr(c)
1998 #define isVERTWS_uni(c)         isVERTWS_uvchr(c)
1999 #define isWORDCHAR_uni(c)       isWORDCHAR_uvchr(c)
2000 #define isXDIGIT_uni(c)         isXDIGIT_uvchr(c)
2001 #define toFOLD_uni(c,s,l)       toFOLD_uvchr(c,s,l)
2002 #define toLOWER_uni(c,s,l)      toLOWER_uvchr(c,s,l)
2003 #define toTITLE_uni(c,s,l)      toTITLE_uvchr(c,s,l)
2004 #define toUPPER_uni(c,s,l)      toUPPER_uvchr(c,s,l)
2005
2006 /* For internal core Perl use only: the base macros for defining macros like
2007  * isALPHA_LC_uvchr.  These are like isALPHA_LC, but the input can be any code
2008  * point, not just 0-255.  Like _generic_uvchr, there are two versions, one for
2009  * simple class definitions; the other for more complex.  These are like
2010  * _generic_uvchr, so see it for more info. */
2011 #define _generic_LC_uvchr(latin1, above_latin1, c)                            \
2012                                     (c < 256 ? latin1(c) : above_latin1(c))
2013 #define _generic_LC_invlist_uvchr(latin1, classnum, c)                          \
2014                             (c < 256 ? latin1(c) : _is_uni_FOO(classnum, c))
2015
2016 #define isALPHA_LC_uvchr(c)  _generic_LC_invlist_uvchr(isALPHA_LC, _CC_ALPHA, c)
2017 #define isALPHANUMERIC_LC_uvchr(c)  _generic_LC_invlist_uvchr(isALPHANUMERIC_LC, \
2018                                                          _CC_ALPHANUMERIC, c)
2019 #define isASCII_LC_uvchr(c)   isASCII_LC(c)
2020 #define isBLANK_LC_uvchr(c)  _generic_LC_uvchr(isBLANK_LC,                    \
2021                                                         is_HORIZWS_cp_high, c)
2022 #define isCNTRL_LC_uvchr(c)  (c < 256 ? isCNTRL_LC(c) : 0)
2023 #define isDIGIT_LC_uvchr(c)  _generic_LC_invlist_uvchr(isDIGIT_LC, _CC_DIGIT, c)
2024 #define isGRAPH_LC_uvchr(c)  _generic_LC_invlist_uvchr(isGRAPH_LC, _CC_GRAPH, c)
2025 #define isIDCONT_LC_uvchr(c) _generic_LC_uvchr(isIDCONT_LC,                   \
2026                                                   _is_uni_perl_idcont, c)
2027 #define isIDFIRST_LC_uvchr(c) _generic_LC_uvchr(isIDFIRST_LC,                 \
2028                                                   _is_uni_perl_idstart, c)
2029 #define isLOWER_LC_uvchr(c)  _generic_LC_invlist_uvchr(isLOWER_LC, _CC_LOWER, c)
2030 #define isPRINT_LC_uvchr(c)  _generic_LC_invlist_uvchr(isPRINT_LC, _CC_PRINT, c)
2031 #define isPSXSPC_LC_uvchr(c)  isSPACE_LC_uvchr(c)
2032 #define isPUNCT_LC_uvchr(c)  _generic_LC_invlist_uvchr(isPUNCT_LC, _CC_PUNCT, c)
2033 #define isSPACE_LC_uvchr(c)  _generic_LC_uvchr(isSPACE_LC,                    \
2034                                                     is_XPERLSPACE_cp_high, c)
2035 #define isUPPER_LC_uvchr(c)  _generic_LC_invlist_uvchr(isUPPER_LC, _CC_UPPER, c)
2036 #define isWORDCHAR_LC_uvchr(c) _generic_LC_invlist_uvchr(isWORDCHAR_LC,         \
2037                                                            _CC_WORDCHAR, c)
2038 #define isXDIGIT_LC_uvchr(c) _generic_LC_uvchr(isXDIGIT_LC,                  \
2039                                                        is_XDIGIT_cp_high, c)
2040
2041 #define isBLANK_LC_uni(c)    isBLANK_LC_uvchr(UNI_TO_NATIVE(c))
2042
2043 /* The "_safe" macros make sure that we don't attempt to read beyond 'e', but
2044  * they don't otherwise go out of their way to look for malformed UTF-8.  If
2045  * they can return accurate results without knowing if the input is otherwise
2046  * malformed, they do so.  For example isASCII is accurate in spite of any
2047  * non-length malformations because it looks only at a single byte. Likewise
2048  * isDIGIT looks just at the first byte for code points 0-255, as all UTF-8
2049  * variant ones return FALSE.  But, if the input has to be well-formed in order
2050  * for the results to be accurate, the macros will test and if malformed will
2051  * call a routine to die
2052  *
2053  * Except for toke.c, the macros do assume that e > p, asserting that on
2054  * DEBUGGING builds.  Much code that calls these depends on this being true,
2055  * for other reasons.  toke.c is treated specially as using the regular
2056  * assertion breaks it in many ways.  All strings that these operate on there
2057  * are supposed to have an extra NUL character at the end,  so that *e = \0. A
2058  * bunch of code in toke.c assumes that this is true, so the assertion allows
2059  * for that */
2060 #ifdef PERL_IN_TOKE_C
2061 #  define _utf8_safe_assert(p,e) ((e) > (p) || ((e) == (p) && *(p) == '\0'))
2062 #else
2063 #  define _utf8_safe_assert(p,e) ((e) > (p))
2064 #endif
2065
2066 #define _generic_utf8_safe(classnum, p, e, above_latin1)                    \
2067     ((! _utf8_safe_assert(p, e))                                            \
2068       ? (_force_out_malformed_utf8_message((U8 *) (p), (U8 *) (e), 0, 1), 0)\
2069       : (UTF8_IS_INVARIANT(*(p)))                                           \
2070           ? _generic_isCC(*(p), classnum)                                   \
2071           : (UTF8_IS_DOWNGRADEABLE_START(*(p))                              \
2072              ? ((LIKELY((e) - (p) > 1 && UTF8_IS_CONTINUATION(*((p)+1))))   \
2073                 ? _generic_isCC(EIGHT_BIT_UTF8_TO_NATIVE(*(p), *((p)+1 )),  \
2074                                 classnum)                                   \
2075                 : (_force_out_malformed_utf8_message(                       \
2076                                         (U8 *) (p), (U8 *) (e), 0, 1), 0))  \
2077              : above_latin1))
2078 /* Like the above, but calls 'above_latin1(p)' to get the utf8 value.
2079  * 'above_latin1' can be a macro */
2080 #define _generic_func_utf8_safe(classnum, above_latin1, p, e)               \
2081                     _generic_utf8_safe(classnum, p, e, above_latin1(p, e))
2082 #define _generic_non_invlist_utf8_safe(classnum, above_latin1, p, e)          \
2083           _generic_utf8_safe(classnum, p, e,                                \
2084                              (UNLIKELY((e) - (p) < UTF8SKIP(p))             \
2085                               ? (_force_out_malformed_utf8_message(         \
2086                                       (U8 *) (p), (U8 *) (e), 0, 1), 0)     \
2087                               : above_latin1(p)))
2088 /* Like the above, but passes classnum to _isFOO_utf8(), instead of having an
2089  * 'above_latin1' parameter */
2090 #define _generic_invlist_utf8_safe(classnum, p, e)                            \
2091             _generic_utf8_safe(classnum, p, e, _is_utf8_FOO(classnum, p, e))
2092
2093 /* Like the above, but should be used only when it is known that there are no
2094  * characters in the upper-Latin1 range (128-255 on ASCII platforms) which the
2095  * class is TRUE for.  Hence it can skip the tests for this range.
2096  * 'above_latin1' should include its arguments */
2097 #define _generic_utf8_safe_no_upper_latin1(classnum, p, e, above_latin1)    \
2098          (__ASSERT_(_utf8_safe_assert(p, e))                                \
2099          (UTF8_IS_INVARIANT(*(p)))                                          \
2100           ? _generic_isCC(*(p), classnum)                                   \
2101           : (UTF8_IS_DOWNGRADEABLE_START(*(p)))                             \
2102              ? 0 /* Note that doesn't check validity for latin1 */          \
2103              : above_latin1)
2104
2105
2106 #define isALPHA_utf8(p, e)         isALPHA_utf8_safe(p, e)
2107 #define isALPHANUMERIC_utf8(p, e)  isALPHANUMERIC_utf8_safe(p, e)
2108 #define isASCII_utf8(p, e)         isASCII_utf8_safe(p, e)
2109 #define isBLANK_utf8(p, e)         isBLANK_utf8_safe(p, e)
2110 #define isCNTRL_utf8(p, e)         isCNTRL_utf8_safe(p, e)
2111 #define isDIGIT_utf8(p, e)         isDIGIT_utf8_safe(p, e)
2112 #define isGRAPH_utf8(p, e)         isGRAPH_utf8_safe(p, e)
2113 #define isIDCONT_utf8(p, e)        isIDCONT_utf8_safe(p, e)
2114 #define isIDFIRST_utf8(p, e)       isIDFIRST_utf8_safe(p, e)
2115 #define isLOWER_utf8(p, e)         isLOWER_utf8_safe(p, e)
2116 #define isPRINT_utf8(p, e)         isPRINT_utf8_safe(p, e)
2117 #define isPSXSPC_utf8(p, e)        isPSXSPC_utf8_safe(p, e)
2118 #define isPUNCT_utf8(p, e)         isPUNCT_utf8_safe(p, e)
2119 #define isSPACE_utf8(p, e)         isSPACE_utf8_safe(p, e)
2120 #define isUPPER_utf8(p, e)         isUPPER_utf8_safe(p, e)
2121 #define isVERTWS_utf8(p, e)        isVERTWS_utf8_safe(p, e)
2122 #define isWORDCHAR_utf8(p, e)      isWORDCHAR_utf8_safe(p, e)
2123 #define isXDIGIT_utf8(p, e)        isXDIGIT_utf8_safe(p, e)
2124
2125 #define isALPHA_utf8_safe(p, e)  _generic_invlist_utf8_safe(_CC_ALPHA, p, e)
2126 #define isALPHANUMERIC_utf8_safe(p, e)                                      \
2127                         _generic_invlist_utf8_safe(_CC_ALPHANUMERIC, p, e)
2128 #define isASCII_utf8_safe(p, e)                                             \
2129     /* Because ASCII is invariant under utf8, the non-utf8 macro            \
2130     * works */                                                              \
2131     (__ASSERT_(_utf8_safe_assert(p, e)) isASCII(*(p)))
2132 #define isBLANK_utf8_safe(p, e)                                             \
2133         _generic_non_invlist_utf8_safe(_CC_BLANK, is_HORIZWS_high, p, e)
2134
2135 #ifdef EBCDIC
2136     /* Because all controls are UTF-8 invariants in EBCDIC, we can use this
2137      * more efficient macro instead of the more general one */
2138 #   define isCNTRL_utf8_safe(p, e)                                          \
2139                     (__ASSERT_(_utf8_safe_assert(p, e)) isCNTRL_L1(*(p)))
2140 #else
2141 #   define isCNTRL_utf8_safe(p, e)  _generic_utf8_safe(_CC_CNTRL, p, e, 0)
2142 #endif
2143
2144 #define isDIGIT_utf8_safe(p, e)                                             \
2145             _generic_utf8_safe_no_upper_latin1(_CC_DIGIT, p, e,             \
2146                                             _is_utf8_FOO(_CC_DIGIT, p, e))
2147 #define isGRAPH_utf8_safe(p, e)    _generic_invlist_utf8_safe(_CC_GRAPH, p, e)
2148 #define isIDCONT_utf8_safe(p, e)   _generic_func_utf8_safe(_CC_WORDCHAR,    \
2149                                                  _is_utf8_perl_idcont, p, e)
2150
2151 /* To prevent S_scan_word in toke.c from hanging, we have to make sure that
2152  * IDFIRST is an alnum.  See
2153  * https://github.com/Perl/perl5/issues/10275 for more detail than you
2154  * ever wanted to know about.  (In the ASCII range, there isn't a difference.)
2155  * This used to be not the XID version, but we decided to go with the more
2156  * modern Unicode definition */
2157 #define isIDFIRST_utf8_safe(p, e)                                           \
2158     _generic_func_utf8_safe(_CC_IDFIRST,                                    \
2159                             _is_utf8_perl_idstart, (U8 *) (p), (U8 *) (e))
2160
2161 #define isLOWER_utf8_safe(p, e)     _generic_invlist_utf8_safe(_CC_LOWER, p, e)
2162 #define isPRINT_utf8_safe(p, e)     _generic_invlist_utf8_safe(_CC_PRINT, p, e)
2163 #define isPSXSPC_utf8_safe(p, e)     isSPACE_utf8_safe(p, e)
2164 #define isPUNCT_utf8_safe(p, e)     _generic_invlist_utf8_safe(_CC_PUNCT, p, e)
2165 #define isSPACE_utf8_safe(p, e)                                             \
2166     _generic_non_invlist_utf8_safe(_CC_SPACE, is_XPERLSPACE_high, p, e)
2167 #define isUPPER_utf8_safe(p, e)  _generic_invlist_utf8_safe(_CC_UPPER, p, e)
2168 #define isVERTWS_utf8_safe(p, e)                                            \
2169         _generic_non_invlist_utf8_safe(_CC_VERTSPACE, is_VERTWS_high, p, e)
2170 #define isWORDCHAR_utf8_safe(p, e)                                          \
2171                              _generic_invlist_utf8_safe(_CC_WORDCHAR, p, e)
2172 #define isXDIGIT_utf8_safe(p, e)                                            \
2173                    _generic_utf8_safe_no_upper_latin1(_CC_XDIGIT, p, e,     \
2174                              (UNLIKELY((e) - (p) < UTF8SKIP(p))             \
2175                               ? (_force_out_malformed_utf8_message(         \
2176                                       (U8 *) (p), (U8 *) (e), 0, 1), 0)     \
2177                               : is_XDIGIT_high(p)))
2178
2179 #define toFOLD_utf8(p,e,s,l)    toFOLD_utf8_safe(p,e,s,l)
2180 #define toLOWER_utf8(p,e,s,l)   toLOWER_utf8_safe(p,e,s,l)
2181 #define toTITLE_utf8(p,e,s,l)   toTITLE_utf8_safe(p,e,s,l)
2182 #define toUPPER_utf8(p,e,s,l)   toUPPER_utf8_safe(p,e,s,l)
2183
2184 /* For internal core use only, subject to change */
2185 #define _toFOLD_utf8_flags(p,e,s,l,f)  _to_utf8_fold_flags (p,e,s,l,f)
2186 #define _toLOWER_utf8_flags(p,e,s,l,f) _to_utf8_lower_flags(p,e,s,l,f)
2187 #define _toTITLE_utf8_flags(p,e,s,l,f) _to_utf8_title_flags(p,e,s,l,f)
2188 #define _toUPPER_utf8_flags(p,e,s,l,f) _to_utf8_upper_flags(p,e,s,l,f)
2189
2190 #define toFOLD_utf8_safe(p,e,s,l)   _toFOLD_utf8_flags(p,e,s,l, FOLD_FLAGS_FULL)
2191 #define toLOWER_utf8_safe(p,e,s,l)  _toLOWER_utf8_flags(p,e,s,l, 0)
2192 #define toTITLE_utf8_safe(p,e,s,l)  _toTITLE_utf8_flags(p,e,s,l, 0)
2193 #define toUPPER_utf8_safe(p,e,s,l)  _toUPPER_utf8_flags(p,e,s,l, 0)
2194
2195 #define isALPHA_LC_utf8(p, e)         isALPHA_LC_utf8_safe(p, e)
2196 #define isALPHANUMERIC_LC_utf8(p, e)  isALPHANUMERIC_LC_utf8_safe(p, e)
2197 #define isASCII_LC_utf8(p, e)         isASCII_LC_utf8_safe(p, e)
2198 #define isBLANK_LC_utf8(p, e)         isBLANK_LC_utf8_safe(p, e)
2199 #define isCNTRL_LC_utf8(p, e)         isCNTRL_LC_utf8_safe(p, e)
2200 #define isDIGIT_LC_utf8(p, e)         isDIGIT_LC_utf8_safe(p, e)
2201 #define isGRAPH_LC_utf8(p, e)         isGRAPH_LC_utf8_safe(p, e)
2202 #define isIDCONT_LC_utf8(p, e)        isIDCONT_LC_utf8_safe(p, e)
2203 #define isIDFIRST_LC_utf8(p, e)       isIDFIRST_LC_utf8_safe(p, e)
2204 #define isLOWER_LC_utf8(p, e)         isLOWER_LC_utf8_safe(p, e)
2205 #define isPRINT_LC_utf8(p, e)         isPRINT_LC_utf8_safe(p, e)
2206 #define isPSXSPC_LC_utf8(p, e)        isPSXSPC_LC_utf8_safe(p, e)
2207 #define isPUNCT_LC_utf8(p, e)         isPUNCT_LC_utf8_safe(p, e)
2208 #define isSPACE_LC_utf8(p, e)         isSPACE_LC_utf8_safe(p, e)
2209 #define isUPPER_LC_utf8(p, e)         isUPPER_LC_utf8_safe(p, e)
2210 #define isWORDCHAR_LC_utf8(p, e)      isWORDCHAR_LC_utf8_safe(p, e)
2211 #define isXDIGIT_LC_utf8(p, e)        isXDIGIT_LC_utf8_safe(p, e)
2212
2213 /* For internal core Perl use only: the base macros for defining macros like
2214  * isALPHA_LC_utf8_safe.  These are like _generic_utf8, but if the first code
2215  * point in 'p' is within the 0-255 range, it uses locale rules from the
2216  * passed-in 'macro' parameter */
2217 #define _generic_LC_utf8_safe(macro, p, e, above_latin1)                    \
2218          (__ASSERT_(_utf8_safe_assert(p, e))                                \
2219          (UTF8_IS_INVARIANT(*(p)))                                          \
2220           ? macro(*(p))                                                     \
2221           : (UTF8_IS_DOWNGRADEABLE_START(*(p))                              \
2222              ? ((LIKELY((e) - (p) > 1 && UTF8_IS_CONTINUATION(*((p)+1))))   \
2223                 ? macro(EIGHT_BIT_UTF8_TO_NATIVE(*(p), *((p)+1)))           \
2224                 : (_force_out_malformed_utf8_message(                       \
2225                                         (U8 *) (p), (U8 *) (e), 0, 1), 0))  \
2226               : above_latin1))
2227
2228 #define _generic_LC_invlist_utf8_safe(macro, classnum, p, e)                  \
2229             _generic_LC_utf8_safe(macro, p, e,                              \
2230                                             _is_utf8_FOO(classnum, p, e))
2231
2232 #define _generic_LC_func_utf8_safe(macro, above_latin1, p, e)               \
2233             _generic_LC_utf8_safe(macro, p, e, above_latin1(p, e))
2234
2235 #define _generic_LC_non_invlist_utf8_safe(classnum, above_latin1, p, e)       \
2236           _generic_LC_utf8_safe(classnum, p, e,                             \
2237                              (UNLIKELY((e) - (p) < UTF8SKIP(p))             \
2238                               ? (_force_out_malformed_utf8_message(         \
2239                                       (U8 *) (p), (U8 *) (e), 0, 1), 0)     \
2240                               : above_latin1(p)))
2241
2242 #define isALPHANUMERIC_LC_utf8_safe(p, e)                                   \
2243             _generic_LC_invlist_utf8_safe(isALPHANUMERIC_LC,                  \
2244                                         _CC_ALPHANUMERIC, p, e)
2245 #define isALPHA_LC_utf8_safe(p, e)                                          \
2246             _generic_LC_invlist_utf8_safe(isALPHA_LC, _CC_ALPHA, p, e)
2247 #define isASCII_LC_utf8_safe(p, e)                                          \
2248                     (__ASSERT_(_utf8_safe_assert(p, e)) isASCII_LC(*(p)))
2249 #define isBLANK_LC_utf8_safe(p, e)                                          \
2250         _generic_LC_non_invlist_utf8_safe(isBLANK_LC, is_HORIZWS_high, p, e)
2251 #define isCNTRL_LC_utf8_safe(p, e)                                          \
2252             _generic_LC_utf8_safe(isCNTRL_LC, p, e, 0)
2253 #define isDIGIT_LC_utf8_safe(p, e)                                          \
2254             _generic_LC_invlist_utf8_safe(isDIGIT_LC, _CC_DIGIT, p, e)
2255 #define isGRAPH_LC_utf8_safe(p, e)                                          \
2256             _generic_LC_invlist_utf8_safe(isGRAPH_LC, _CC_GRAPH, p, e)
2257 #define isIDCONT_LC_utf8_safe(p, e)                                         \
2258             _generic_LC_func_utf8_safe(isIDCONT_LC,                         \
2259                                                 _is_utf8_perl_idcont, p, e)
2260 #define isIDFIRST_LC_utf8_safe(p, e)                                        \
2261             _generic_LC_func_utf8_safe(isIDFIRST_LC,                        \
2262                                                _is_utf8_perl_idstart, p, e)
2263 #define isLOWER_LC_utf8_safe(p, e)                                          \
2264             _generic_LC_invlist_utf8_safe(isLOWER_LC, _CC_LOWER, p, e)
2265 #define isPRINT_LC_utf8_safe(p, e)                                          \
2266             _generic_LC_invlist_utf8_safe(isPRINT_LC, _CC_PRINT, p, e)
2267 #define isPSXSPC_LC_utf8_safe(p, e)    isSPACE_LC_utf8_safe(p, e)
2268 #define isPUNCT_LC_utf8_safe(p, e)                                          \
2269             _generic_LC_invlist_utf8_safe(isPUNCT_LC, _CC_PUNCT, p, e)
2270 #define isSPACE_LC_utf8_safe(p, e)                                          \
2271     _generic_LC_non_invlist_utf8_safe(isSPACE_LC, is_XPERLSPACE_high, p, e)
2272 #define isUPPER_LC_utf8_safe(p, e)                                          \
2273             _generic_LC_invlist_utf8_safe(isUPPER_LC, _CC_UPPER, p, e)
2274 #define isWORDCHAR_LC_utf8_safe(p, e)                                       \
2275             _generic_LC_invlist_utf8_safe(isWORDCHAR_LC, _CC_WORDCHAR, p, e)
2276 #define isXDIGIT_LC_utf8_safe(p, e)                                         \
2277         _generic_LC_non_invlist_utf8_safe(isXDIGIT_LC, is_XDIGIT_high, p, e)
2278
2279 /* Macros for backwards compatibility and for completeness when the ASCII and
2280  * Latin1 values are identical */
2281 #define isALPHAU(c)         isALPHA_L1(c)
2282 #define isDIGIT_L1(c)       isDIGIT_A(c)
2283 #define isOCTAL(c)          isOCTAL_A(c)
2284 #define isOCTAL_L1(c)       isOCTAL_A(c)
2285 #define isXDIGIT_L1(c)      isXDIGIT_A(c)
2286 #define isALNUM(c)          isWORDCHAR(c)
2287 #define isALNUM_A(c)        isALNUM(c)
2288 #define isALNUMU(c)         isWORDCHAR_L1(c)
2289 #define isALNUM_LC(c)       isWORDCHAR_LC(c)
2290 #define isALNUM_uni(c)      isWORDCHAR_uni(c)
2291 #define isALNUM_LC_uvchr(c) isWORDCHAR_LC_uvchr(c)
2292 #define isALNUM_utf8(p,e)   isWORDCHAR_utf8(p,e)
2293 #define isALNUM_utf8_safe(p,e) isWORDCHAR_utf8_safe(p,e)
2294 #define isALNUM_LC_utf8(p,e)isWORDCHAR_LC_utf8(p,e)
2295 #define isALNUM_LC_utf8_safe(p,e)isWORDCHAR_LC_utf8_safe(p,e)
2296 #define isALNUMC_A(c)       isALPHANUMERIC_A(c)      /* Mnemonic: "C's alnum" */
2297 #define isALNUMC_L1(c)      isALPHANUMERIC_L1(c)
2298 #define isALNUMC(c)         isALPHANUMERIC(c)
2299 #define isALNUMC_LC(c)      isALPHANUMERIC_LC(c)
2300 #define isALNUMC_uni(c)     isALPHANUMERIC_uni(c)
2301 #define isALNUMC_LC_uvchr(c) isALPHANUMERIC_LC_uvchr(c)
2302 #define isALNUMC_utf8(p,e)  isALPHANUMERIC_utf8(p,e)
2303 #define isALNUMC_utf8_safe(p,e)  isALPHANUMERIC_utf8_safe(p,e)
2304 #define isALNUMC_LC_utf8_safe(p,e) isALPHANUMERIC_LC_utf8_safe(p,e)
2305
2306 /* On EBCDIC platforms, CTRL-@ is 0, CTRL-A is 1, etc, just like on ASCII,
2307  * except that they don't necessarily mean the same characters, e.g. CTRL-D is
2308  * 4 on both systems, but that is EOT on ASCII;  ST on EBCDIC.
2309  * '?' is special-cased on EBCDIC to APC, which is the control there that is
2310  * the outlier from the block that contains the other controls, just like
2311  * toCTRL('?') on ASCII yields DEL, the control that is the outlier from the C0
2312  * block.  If it weren't special cased, it would yield a non-control.
2313  * The conversion works both ways, so toCTRL('D') is 4, and toCTRL(4) is D,
2314  * etc. */
2315 #ifndef EBCDIC
2316 #  define toCTRL(c)    (__ASSERT_(FITS_IN_8_BITS(c)) toUPPER(((U8)(c))) ^ 64)
2317 #else
2318 #  define toCTRL(c)   (__ASSERT_(FITS_IN_8_BITS(c))                     \
2319                       ((isPRINT_A(c))                                   \
2320                        ? (UNLIKELY((c) == '?')                          \
2321                          ? QUESTION_MARK_CTRL                           \
2322                          : (NATIVE_TO_LATIN1(toUPPER((U8) (c))) ^ 64))  \
2323                        : (UNLIKELY((c) == QUESTION_MARK_CTRL)           \
2324                          ? '?'                                          \
2325                          : (LATIN1_TO_NATIVE(((U8) (c)) ^ 64)))))
2326 #endif
2327
2328 /* Line numbers are unsigned, 32 bits. */
2329 typedef U32 line_t;
2330 #define NOLINE ((line_t) 4294967295UL)  /* = FFFFFFFF */
2331
2332 /* Helpful alias for version prescan */
2333 #define is_LAX_VERSION(a,b) \
2334         (a != Perl_prescan_version(aTHX_ a, FALSE, b, NULL, NULL, NULL, NULL))
2335
2336 #define is_STRICT_VERSION(a,b) \
2337         (a != Perl_prescan_version(aTHX_ a, TRUE, b, NULL, NULL, NULL, NULL))
2338
2339 #define BADVERSION(a,b,c) \
2340         if (b) { \
2341             *b = c; \
2342         } \
2343         return a;
2344
2345 /* Converts a character KNOWN to represent a hexadecimal digit (0-9, A-F, or
2346  * a-f) to its numeric value without using any branches.  The input is
2347  * validated only by an assert() in DEBUGGING builds.
2348  *
2349  * It works by right shifting and isolating the bit that is 0 for the digits,
2350  * and 1 for at least the alphas A-F, a-f.  The bit is shifted to the ones
2351  * position, and then to the eights position.  Both are added together to form
2352  * 0 if the input is '0'-'9' and to form 9 if alpha.  This is added to the
2353  * final four bits of the input to form the correct value. */
2354 #define XDIGIT_VALUE(c) (__ASSERT_(isXDIGIT(c))                             \
2355            ((NATIVE_TO_LATIN1(c) >> 6) & 1)  /* 1 if alpha; 0 if not */     \
2356          + ((NATIVE_TO_LATIN1(c) >> 3) & 8)  /* 8 if alpha; 0 if not */     \
2357          + ((c) & 0xF))   /* 0-9 if input valid hex digit */
2358
2359 /* The argument is a string pointer, which is advanced. */
2360 #define READ_XDIGIT(s)  ((s)++, XDIGIT_VALUE(*((s) - 1)))
2361
2362 /* Converts a character known to represent an octal digit (0-7) to its numeric
2363  * value.  The input is validated only by an assert() in DEBUGGING builds.  In
2364  * both ASCII and EBCDIC the last 3 bits of the octal digits range from 0-7. */
2365 #define OCTAL_VALUE(c) (__ASSERT_(isOCTAL(c)) (7 & (c)))
2366
2367 /* Efficiently returns a boolean as to if two native characters are equivalent
2368  * case-insenstively.  At least one of the characters must be one of [A-Za-z];
2369  * the ALPHA in the name is to remind you of that.  This is asserted() in
2370  * DEBUGGING builds.  Because [A-Za-z] are invariant under UTF-8, this macro
2371  * works (on valid input) for both non- and UTF-8-encoded bytes.
2372  *
2373  * When one of the inputs is a compile-time constant and gets folded by the
2374  * compiler, this reduces to an AND and a TEST.  On both EBCDIC and ASCII
2375  * machines, 'A' and 'a' differ by a single bit; the same with the upper and
2376  * lower case of all other ASCII-range alphabetics.  On ASCII platforms, they
2377  * are 32 apart; on EBCDIC, they are 64.  At compile time, this uses an
2378  * exclusive 'or' to find that bit and then inverts it to form a mask, with
2379  * just a single 0, in the bit position where the upper- and lowercase differ.
2380  * */
2381 #define isALPHA_FOLD_EQ(c1, c2)                                         \
2382                       (__ASSERT_(isALPHA_A(c1) || isALPHA_A(c2))        \
2383                       ((c1) & ~('A' ^ 'a')) ==  ((c2) & ~('A' ^ 'a')))
2384 #define isALPHA_FOLD_NE(c1, c2) (! isALPHA_FOLD_EQ((c1), (c2)))
2385
2386 /*
2387 =head1 Memory Management
2388
2389 =for apidoc Am|void|Newx|void* ptr|int nitems|type
2390 The XSUB-writer's interface to the C C<malloc> function.
2391
2392 Memory obtained by this should B<ONLY> be freed with L</"Safefree">.
2393
2394 In 5.9.3, Newx() and friends replace the older New() API, and drops
2395 the first parameter, I<x>, a debug aid which allowed callers to identify
2396 themselves.  This aid has been superseded by a new build option,
2397 PERL_MEM_LOG (see L<perlhacktips/PERL_MEM_LOG>).  The older API is still
2398 there for use in XS modules supporting older perls.
2399
2400 =for apidoc Am|void|Newxc|void* ptr|int nitems|type|cast
2401 The XSUB-writer's interface to the C C<malloc> function, with
2402 cast.  See also C<L</Newx>>.
2403
2404 Memory obtained by this should B<ONLY> be freed with L</"Safefree">.
2405
2406 =for apidoc Am|void|Newxz|void* ptr|int nitems|type
2407 The XSUB-writer's interface to the C C<malloc> function.  The allocated
2408 memory is zeroed with C<memzero>.  See also C<L</Newx>>.
2409
2410 Memory obtained by this should B<ONLY> be freed with L</"Safefree">.
2411
2412 =for apidoc Am|void|Renew|void* ptr|int nitems|type
2413 The XSUB-writer's interface to the C C<realloc> function.
2414
2415 Memory obtained by this should B<ONLY> be freed with L</"Safefree">.
2416
2417 =for apidoc Am|void|Renewc|void* ptr|int nitems|type|cast
2418 The XSUB-writer's interface to the C C<realloc> function, with
2419 cast.
2420
2421 Memory obtained by this should B<ONLY> be freed with L</"Safefree">.
2422
2423 =for apidoc Am|void|Safefree|void* ptr
2424 The XSUB-writer's interface to the C C<free> function.
2425
2426 This should B<ONLY> be used on memory obtained using L</"Newx"> and friends.
2427
2428 =for apidoc Am|void|Move|void* src|void* dest|int nitems|type
2429 The XSUB-writer's interface to the C C<memmove> function.  The C<src> is the
2430 source, C<dest> is the destination, C<nitems> is the number of items, and
2431 C<type> is the type.  Can do overlapping moves.  See also C<L</Copy>>.
2432
2433 =for apidoc Am|void *|MoveD|void* src|void* dest|int nitems|type
2434 Like C<Move> but returns C<dest>.  Useful
2435 for encouraging compilers to tail-call
2436 optimise.
2437
2438 =for apidoc Am|void|Copy|void* src|void* dest|int nitems|type
2439 The XSUB-writer's interface to the C C<memcpy> function.  The C<src> is the
2440 source, C<dest> is the destination, C<nitems> is the number of items, and
2441 C<type> is the type.  May fail on overlapping copies.  See also C<L</Move>>.
2442
2443 =for apidoc Am|void *|CopyD|void* src|void* dest|int nitems|type
2444
2445 Like C<Copy> but returns C<dest>.  Useful
2446 for encouraging compilers to tail-call
2447 optimise.
2448
2449 =for apidoc Am|void|Zero|void* dest|int nitems|type
2450
2451 The XSUB-writer's interface to the C C<memzero> function.  The C<dest> is the
2452 destination, C<nitems> is the number of items, and C<type> is the type.
2453
2454 =for apidoc Am|void *|ZeroD|void* dest|int nitems|type
2455
2456 Like C<Zero> but returns dest.  Useful
2457 for encouraging compilers to tail-call
2458 optimise.
2459
2460 =for apidoc Am|void|StructCopy|type *src|type *dest|type
2461 This is an architecture-independent macro to copy one structure to another.
2462
2463 =for apidoc Am|void|PoisonWith|void* dest|int nitems|type|U8 byte
2464
2465 Fill up memory with a byte pattern (a byte repeated over and over
2466 again) that hopefully catches attempts to access uninitialized memory.
2467
2468 =for apidoc Am|void|PoisonNew|void* dest|int nitems|type
2469
2470 PoisonWith(0xAB) for catching access to allocated but uninitialized memory.
2471
2472 =for apidoc Am|void|PoisonFree|void* dest|int nitems|type
2473
2474 PoisonWith(0xEF) for catching access to freed memory.
2475
2476 =for apidoc Am|void|Poison|void* dest|int nitems|type
2477
2478 PoisonWith(0xEF) for catching access to freed memory.
2479
2480 =cut */
2481
2482 /* Maintained for backwards-compatibility only. Use newSV() instead. */
2483 #ifndef PERL_CORE
2484 #define NEWSV(x,len)    newSV(len)
2485 #endif
2486
2487 #define MEM_SIZE_MAX ((MEM_SIZE)-1)
2488
2489 #define _PERL_STRLEN_ROUNDUP_UNCHECKED(n) (((n) - 1 + PERL_STRLEN_ROUNDUP_QUANTUM) & ~((MEM_SIZE)PERL_STRLEN_ROUNDUP_QUANTUM - 1))
2490
2491 #ifdef PERL_MALLOC_WRAP
2492
2493 /* This expression will be constant-folded at compile time.  It checks
2494  * whether or not the type of the count n is so small (e.g. U8 or U16, or
2495  * U32 on 64-bit systems) that there's no way a wrap-around could occur.
2496  * As well as avoiding the need for a run-time check in some cases, it's
2497  * designed to avoid compiler warnings like:
2498  *     comparison is always false due to limited range of data type
2499  * It's mathematically equivalent to
2500  *    max(n) * sizeof(t) > MEM_SIZE_MAX
2501  */
2502
2503 #  define _MEM_WRAP_NEEDS_RUNTIME_CHECK(n,t) \
2504     (  sizeof(MEM_SIZE) < sizeof(n) \
2505     || sizeof(t) > ((MEM_SIZE)1 << 8*(sizeof(MEM_SIZE) - sizeof(n))))
2506
2507 /* This is written in a slightly odd way to avoid various spurious
2508  * compiler warnings. We *want* to write the expression as
2509  *    _MEM_WRAP_NEEDS_RUNTIME_CHECK(n,t) && (n > C)
2510  * (for some compile-time constant C), but even when the LHS
2511  * constant-folds to false at compile-time, g++ insists on emitting
2512  * warnings about the RHS (e.g. "comparison is always false"), so instead
2513  * we write it as
2514  *
2515  *    (cond ? n : X) > C
2516  *
2517  * where X is a constant with X > C always false. Choosing a value for X
2518  * is tricky. If 0, some compilers will complain about 0 > C always being
2519  * false; if 1, Coverity complains when n happens to be the constant value
2520  * '1', that cond ? 1 : 1 has the same value on both branches; so use C
2521  * for X and hope that nothing else whines.
2522  */
2523
2524 #  define _MEM_WRAP_WILL_WRAP(n,t) \
2525       ((_MEM_WRAP_NEEDS_RUNTIME_CHECK(n,t) ? (MEM_SIZE)(n) : \
2526             MEM_SIZE_MAX/sizeof(t)) > MEM_SIZE_MAX/sizeof(t))
2527
2528 #  define MEM_WRAP_CHECK(n,t) \
2529         (void)(UNLIKELY(_MEM_WRAP_WILL_WRAP(n,t)) \
2530         && (croak_memory_wrap(),0))
2531
2532 #  define MEM_WRAP_CHECK_1(n,t,a) \
2533         (void)(UNLIKELY(_MEM_WRAP_WILL_WRAP(n,t)) \
2534         && (Perl_croak_nocontext("%s",(a)),0))
2535
2536 /* "a" arg must be a string literal */
2537 #  define MEM_WRAP_CHECK_s(n,t,a) \
2538         (void)(UNLIKELY(_MEM_WRAP_WILL_WRAP(n,t)) \
2539         && (Perl_croak_nocontext("" a ""),0))
2540
2541 #define MEM_WRAP_CHECK_(n,t) MEM_WRAP_CHECK(n,t),
2542
2543 #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))
2544 #else
2545
2546 #define MEM_WRAP_CHECK(n,t)
2547 #define MEM_WRAP_CHECK_1(n,t,a)
2548 #define MEM_WRAP_CHECK_s(n,t,a)
2549 #define MEM_WRAP_CHECK_(n,t)
2550
2551 #define PERL_STRLEN_ROUNDUP(n) _PERL_STRLEN_ROUNDUP_UNCHECKED(n)
2552
2553 #endif
2554
2555 #ifdef PERL_MEM_LOG
2556 /*
2557  * If PERL_MEM_LOG is defined, all Newx()s, Renew()s, and Safefree()s
2558  * go through functions, which are handy for debugging breakpoints, but
2559  * which more importantly get the immediate calling environment (file and
2560  * line number, and C function name if available) passed in.  This info can
2561  * then be used for logging the calls, for which one gets a sample
2562  * implementation unless -DPERL_MEM_LOG_NOIMPL is also defined.
2563  *
2564  * Known problems:
2565  * - not all memory allocs get logged, only those
2566  *   that go through Newx() and derivatives (while all
2567  *   Safefrees do get logged)
2568  * - __FILE__ and __LINE__ do not work everywhere
2569  * - __func__ or __FUNCTION__ even less so
2570  * - I think more goes on after the perlio frees but
2571  *   the thing is that STDERR gets closed (as do all
2572  *   the file descriptors)
2573  * - no deeper calling stack than the caller of the Newx()
2574  *   or the kind, but do I look like a C reflection/introspection
2575  *   utility to you?
2576  * - the function prototypes for the logging functions
2577  *   probably should maybe be somewhere else than handy.h
2578  * - one could consider inlining (macrofying) the logging
2579  *   for speed, but I am too lazy
2580  * - one could imagine recording the allocations in a hash,
2581  *   (keyed by the allocation address?), and maintain that
2582  *   through reallocs and frees, but how to do that without
2583  *   any News() happening...?
2584  * - lots of -Ddefines to get useful/controllable output
2585  * - lots of ENV reads
2586  */
2587
2588 # ifdef PERL_CORE
2589 #  ifndef PERL_MEM_LOG_NOIMPL
2590 enum mem_log_type {
2591   MLT_ALLOC,
2592   MLT_REALLOC,
2593   MLT_FREE,
2594   MLT_NEW_SV,
2595   MLT_DEL_SV
2596 };
2597 #  endif
2598 #  if defined(PERL_IN_SV_C)  /* those are only used in sv.c */
2599 void Perl_mem_log_new_sv(const SV *sv, const char *filename, const int linenumber, const char *funcname);
2600 void Perl_mem_log_del_sv(const SV *sv, const char *filename, const int linenumber, const char *funcname);
2601 #  endif
2602 # endif
2603
2604 #endif
2605
2606 #ifdef PERL_MEM_LOG
2607 #define MEM_LOG_ALLOC(n,t,a)     Perl_mem_log_alloc(n,sizeof(t),STRINGIFY(t),a,__FILE__,__LINE__,FUNCTION__)
2608 #define MEM_LOG_REALLOC(n,t,v,a) Perl_mem_log_realloc(n,sizeof(t),STRINGIFY(t),v,a,__FILE__,__LINE__,FUNCTION__)
2609 #define MEM_LOG_FREE(a)          Perl_mem_log_free(a,__FILE__,__LINE__,FUNCTION__)
2610 #endif
2611
2612 #ifndef MEM_LOG_ALLOC
2613 #define MEM_LOG_ALLOC(n,t,a)     (a)
2614 #endif
2615 #ifndef MEM_LOG_REALLOC
2616 #define MEM_LOG_REALLOC(n,t,v,a) (a)
2617 #endif
2618 #ifndef MEM_LOG_FREE
2619 #define MEM_LOG_FREE(a)          (a)
2620 #endif
2621
2622 #define Newx(v,n,t)     (v = (MEM_WRAP_CHECK_(n,t) (t*)MEM_LOG_ALLOC(n,t,safemalloc((MEM_SIZE)((n)*sizeof(t))))))
2623 #define Newxc(v,n,t,c)  (v = (MEM_WRAP_CHECK_(n,t) (c*)MEM_LOG_ALLOC(n,t,safemalloc((MEM_SIZE)((n)*sizeof(t))))))
2624 #define Newxz(v,n,t)    (v = (MEM_WRAP_CHECK_(n,t) (t*)MEM_LOG_ALLOC(n,t,safecalloc((n),sizeof(t)))))
2625
2626 #ifndef PERL_CORE
2627 /* pre 5.9.x compatibility */
2628 #define New(x,v,n,t)    Newx(v,n,t)
2629 #define Newc(x,v,n,t,c) Newxc(v,n,t,c)
2630 #define Newz(x,v,n,t)   Newxz(v,n,t)
2631 #endif
2632
2633 #define Renew(v,n,t) \
2634           (v = (MEM_WRAP_CHECK_(n,t) (t*)MEM_LOG_REALLOC(n,t,v,saferealloc((Malloc_t)(v),(MEM_SIZE)((n)*sizeof(t))))))
2635 #define Renewc(v,n,t,c) \
2636           (v = (MEM_WRAP_CHECK_(n,t) (c*)MEM_LOG_REALLOC(n,t,v,saferealloc((Malloc_t)(v),(MEM_SIZE)((n)*sizeof(t))))))
2637
2638 #ifdef PERL_POISON
2639 #define Safefree(d) \
2640   ((d) ? (void)(safefree(MEM_LOG_FREE((Malloc_t)(d))), Poison(&(d), 1, Malloc_t)) : (void) 0)
2641 #else
2642 #define Safefree(d)     safefree(MEM_LOG_FREE((Malloc_t)(d)))
2643 #endif
2644
2645 /* assert that a valid ptr has been supplied - use this instead of assert(ptr)  *
2646  * as it handles cases like constant string arguments without throwing warnings *
2647  * the cast is required, as is the inequality check, to avoid warnings          */
2648 #define perl_assert_ptr(p) assert( ((void*)(p)) != 0 )
2649
2650
2651 #define Move(s,d,n,t)   (MEM_WRAP_CHECK_(n,t) perl_assert_ptr(d), perl_assert_ptr(s), (void)memmove((char*)(d),(const char*)(s), (n) * sizeof(t)))
2652 #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)))
2653 #define Zero(d,n,t)     (MEM_WRAP_CHECK_(n,t) perl_assert_ptr(d), (void)memzero((char*)(d), (n) * sizeof(t)))
2654
2655 /* Like above, but returns a pointer to 'd' */
2656 #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)))
2657 #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)))
2658 #define ZeroD(d,n,t)    (MEM_WRAP_CHECK_(n,t) perl_assert_ptr(d), memzero((char*)(d), (n) * sizeof(t)))
2659
2660 #define PoisonWith(d,n,t,b)     (MEM_WRAP_CHECK_(n,t) (void)memset((char*)(d), (U8)(b), (n) * sizeof(t)))
2661 #define PoisonNew(d,n,t)        PoisonWith(d,n,t,0xAB)
2662 #define PoisonFree(d,n,t)       PoisonWith(d,n,t,0xEF)
2663 #define Poison(d,n,t)           PoisonFree(d,n,t)
2664
2665 #ifdef PERL_POISON
2666 #  define PERL_POISON_EXPR(x) x
2667 #else
2668 #  define PERL_POISON_EXPR(x)
2669 #endif
2670
2671 #define StructCopy(s,d,t) (*((t*)(d)) = *((t*)(s)))
2672
2673 /*
2674 =head1 Handy Values
2675
2676 =for apidoc Am|STRLEN|C_ARRAY_LENGTH|void *a
2677
2678 Returns the number of elements in the input C array (so you want your
2679 zero-based indices to be less than but not equal to).
2680
2681 =for apidoc Am|void *|C_ARRAY_END|void *a
2682
2683 Returns a pointer to one element past the final element of the input C array.
2684
2685 =cut
2686
2687 C_ARRAY_END is one past the last: half-open/half-closed range, not
2688 last-inclusive range.
2689 */
2690 #define C_ARRAY_LENGTH(a)       (sizeof(a)/sizeof((a)[0]))
2691 #define C_ARRAY_END(a)          ((a) + C_ARRAY_LENGTH(a))
2692
2693 #ifdef NEED_VA_COPY
2694 # ifdef va_copy
2695 #  define Perl_va_copy(s, d) va_copy(d, s)
2696 # elif defined(__va_copy)
2697 #  define Perl_va_copy(s, d) __va_copy(d, s)
2698 # else
2699 #  define Perl_va_copy(s, d) Copy(s, d, 1, va_list)
2700 # endif
2701 #endif
2702
2703 /* convenience debug macros */
2704 #ifdef USE_ITHREADS
2705 #define pTHX_FORMAT  "Perl interpreter: 0x%p"
2706 #define pTHX__FORMAT ", Perl interpreter: 0x%p"
2707 #define pTHX_VALUE_   (void *)my_perl,
2708 #define pTHX_VALUE    (void *)my_perl
2709 #define pTHX__VALUE_ ,(void *)my_perl,
2710 #define pTHX__VALUE  ,(void *)my_perl
2711 #else
2712 #define pTHX_FORMAT
2713 #define pTHX__FORMAT
2714 #define pTHX_VALUE_
2715 #define pTHX_VALUE
2716 #define pTHX__VALUE_
2717 #define pTHX__VALUE
2718 #endif /* USE_ITHREADS */
2719
2720 /* Perl_deprecate was not part of the public API, and did not have a deprecate()
2721    shortcut macro defined without -DPERL_CORE. Neither codesearch.google.com nor
2722    CPAN::Unpack show any users outside the core.  */
2723 #ifdef PERL_CORE
2724 #  define deprecate(s) Perl_ck_warner_d(aTHX_ packWARN(WARN_DEPRECATED),    \
2725                                             "Use of " s " is deprecated")
2726 #  define deprecate_disappears_in(when,message) \
2727               Perl_ck_warner_d(aTHX_ packWARN(WARN_DEPRECATED),    \
2728                                message ", and will disappear in Perl " when)
2729 #  define deprecate_fatal_in(when,message) \
2730               Perl_ck_warner_d(aTHX_ packWARN(WARN_DEPRECATED),    \
2731                                message ". Its use will be fatal in Perl " when)
2732 #endif
2733
2734 /* Internal macros to deal with gids and uids */
2735 #ifdef PERL_CORE
2736
2737 #  if Uid_t_size > IVSIZE
2738 #    define sv_setuid(sv, uid)       sv_setnv((sv), (NV)(uid))
2739 #    define SvUID(sv)                SvNV(sv)
2740 #  elif Uid_t_sign <= 0
2741 #    define sv_setuid(sv, uid)       sv_setiv((sv), (IV)(uid))
2742 #    define SvUID(sv)                SvIV(sv)
2743 #  else
2744 #    define sv_setuid(sv, uid)       sv_setuv((sv), (UV)(uid))
2745 #    define SvUID(sv)                SvUV(sv)
2746 #  endif /* Uid_t_size */
2747
2748 #  if Gid_t_size > IVSIZE
2749 #    define sv_setgid(sv, gid)       sv_setnv((sv), (NV)(gid))
2750 #    define SvGID(sv)                SvNV(sv)
2751 #  elif Gid_t_sign <= 0
2752 #    define sv_setgid(sv, gid)       sv_setiv((sv), (IV)(gid))
2753 #    define SvGID(sv)                SvIV(sv)
2754 #  else
2755 #    define sv_setgid(sv, gid)       sv_setuv((sv), (UV)(gid))
2756 #    define SvGID(sv)                SvUV(sv)
2757 #  endif /* Gid_t_size */
2758
2759 #endif
2760
2761 #endif  /* PERL_HANDY_H_ */
2762
2763 /*
2764  * ex: set ts=8 sts=4 sw=4 et:
2765  */