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