This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perlapi: Consolidate sv_catpvn-ish entries
[perl5.git] / mathoms.c
CommitLineData
7ee2227d
SP
1/* mathoms.c
2 *
2eee27d7
SS
3 * Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010,
4 * 2011, 2012 by Larry Wall and others
7ee2227d
SP
5 *
6 * You may distribute under the terms of either the GNU General Public
7 * License or the Artistic License, as specified in the README file.
8 *
9 */
10
11/*
4ac71550
TC
12 * Anything that Hobbits had no immediate use for, but were unwilling to
13 * throw away, they called a mathom. Their dwellings were apt to become
14 * rather crowded with mathoms, and many of the presents that passed from
15 * hand to hand were of that sort.
16 *
17 * [p.5 of _The Lord of the Rings_: "Prologue"]
7ee2227d
SP
18 */
19
359d40ba 20
20fac488 21
7832ad85 22/*
7ee2227d 23 * This file contains mathoms, various binary artifacts from previous
d7244c9a
DM
24 * versions of Perl which we cannot completely remove from the core
25 * code. There are two reasons functions should be here:
26 *
a3815e44 27 * 1) A function has been replaced by a macro within a minor release,
d7244c9a
DM
28 * so XS modules compiled against an older release will expect to
29 * still be able to link against the function
30 * 2) A function Perl_foo(...) with #define foo Perl_foo(aTHX_ ...)
31 * has been replaced by a macro, e.g. #define foo(...) foo_flags(...,0)
32 * but XS code may still explicitly use the long form, i.e.
33 * Perl_foo(aTHX_ ...)
7ee2227d 34 *
8687a6e6
DM
35 * NOTE: ALL FUNCTIONS IN THIS FILE should have an entry with the 'b' flag in
36 * embed.fnc.
37 *
38 * To move a function to this file, simply cut and paste it here, and change
39 * its embed.fnc entry to additionally have the 'b' flag. If, for some reason
40 * a function you'd like to be treated as mathoms can't be moved from its
41 * current place, simply enclose it between
42 *
43 * #ifndef NO_MATHOMS
44 * ...
45 * #endif
46 *
47 * and add the 'b' flag in embed.fnc.
48 *
55cb5ee0
KW
49 * The compilation of this file can be suppressed; see INSTALL
50 *
8687a6e6
DM
51 * Some blurb for perlapi.pod:
52
51b56f5c 53 head1 Obsolete backwards compatibility functions
8687a6e6 54
dcccc8ff
KW
55Some of these are also deprecated. You can exclude these from
56your compiled Perl by adding this option to Configure:
57C<-Accflags='-DNO_MATHOMS'>
58
59=cut
60
7ee2227d
SP
61 */
62
dcccc8ff 63
7ee2227d
SP
64#include "EXTERN.h"
65#define PERL_IN_MATHOMS_C
66#include "perl.h"
67
359d40ba
NC
68#ifdef NO_MATHOMS
69/* ..." warning: ISO C forbids an empty source file"
70 So make sure we have something in here by processing the headers anyway.
71 */
72#else
73
238965b4
KW
74/* The functions in this file should be able to call other deprecated functions
75 * without a compiler warning */
76GCC_DIAG_IGNORE(-Wdeprecated-declarations)
77
7ee2227d
SP
78/* ref() is now a macro using Perl_doref;
79 * this version provided for binary compatibility only.
80 */
81OP *
82Perl_ref(pTHX_ OP *o, I32 type)
83{
84 return doref(o, type, TRUE);
85}
86
aae9cea0 87/*
3f620621 88=for apidoc_section $SV
174c73e3
NC
89=for apidoc sv_unref
90
91Unsets the RV status of the SV, and decrements the reference count of
92whatever was being referenced by the RV. This can almost be thought of
93as a reversal of C<newSVrv>. This is C<sv_unref_flags> with the C<flag>
fbe13c60 94being zero. See C<L</SvROK_off>>.
174c73e3
NC
95
96=cut
97*/
98
99void
100Perl_sv_unref(pTHX_ SV *sv)
101{
7918f24d
NC
102 PERL_ARGS_ASSERT_SV_UNREF;
103
174c73e3
NC
104 sv_unref_flags(sv, 0);
105}
106
107/*
aae9cea0
NC
108=for apidoc sv_taint
109
72d33970 110Taint an SV. Use C<SvTAINTED_on> instead.
dff47061 111
aae9cea0
NC
112=cut
113*/
114
115void
116Perl_sv_taint(pTHX_ SV *sv)
117{
7918f24d
NC
118 PERL_ARGS_ASSERT_SV_TAINT;
119
a0714e2c 120 sv_magic((sv), NULL, PERL_MAGIC_taint, NULL, 0);
aae9cea0
NC
121}
122
7ee2227d
SP
123/* sv_2iv() is now a macro using Perl_sv_2iv_flags();
124 * this function provided for binary compatibility only
125 */
126
127IV
5aaab254 128Perl_sv_2iv(pTHX_ SV *sv)
7ee2227d 129{
1061065f
DD
130 PERL_ARGS_ASSERT_SV_2IV;
131
7ee2227d
SP
132 return sv_2iv_flags(sv, SV_GMAGIC);
133}
134
135/* sv_2uv() is now a macro using Perl_sv_2uv_flags();
136 * this function provided for binary compatibility only
137 */
138
139UV
5aaab254 140Perl_sv_2uv(pTHX_ SV *sv)
7ee2227d 141{
1061065f
DD
142 PERL_ARGS_ASSERT_SV_2UV;
143
7ee2227d
SP
144 return sv_2uv_flags(sv, SV_GMAGIC);
145}
146
39d5de13
DM
147/* sv_2nv() is now a macro using Perl_sv_2nv_flags();
148 * this function provided for binary compatibility only
149 */
150
151NV
5aaab254 152Perl_sv_2nv(pTHX_ SV *sv)
39d5de13
DM
153{
154 return sv_2nv_flags(sv, SV_GMAGIC);
155}
156
157
7ee2227d
SP
158/* sv_2pv() is now a macro using Perl_sv_2pv_flags();
159 * this function provided for binary compatibility only
160 */
161
162char *
5aaab254 163Perl_sv_2pv(pTHX_ SV *sv, STRLEN *lp)
7ee2227d 164{
1061065f
DD
165 PERL_ARGS_ASSERT_SV_2PV;
166
7ee2227d
SP
167 return sv_2pv_flags(sv, lp, SV_GMAGIC);
168}
169
5abc721d 170/*
cb2f1b7b
NC
171=for apidoc sv_2pv_nolen
172
72d33970 173Like C<sv_2pv()>, but doesn't return the length too. You should usually
cb2f1b7b 174use the macro wrapper C<SvPV_nolen(sv)> instead.
dff47061 175
cb2f1b7b
NC
176=cut
177*/
178
179char *
5aaab254 180Perl_sv_2pv_nolen(pTHX_ SV *sv)
cb2f1b7b 181{
c85ae797 182 PERL_ARGS_ASSERT_SV_2PV_NOLEN;
b5445a23 183 return sv_2pv(sv, NULL);
cb2f1b7b
NC
184}
185
186/*
187=for apidoc sv_2pvbyte_nolen
188
189Return a pointer to the byte-encoded representation of the SV.
190May cause the SV to be downgraded from UTF-8 as a side-effect.
191
192Usually accessed via the C<SvPVbyte_nolen> macro.
193
194=cut
195*/
196
197char *
5aaab254 198Perl_sv_2pvbyte_nolen(pTHX_ SV *sv)
cb2f1b7b 199{
7918f24d
NC
200 PERL_ARGS_ASSERT_SV_2PVBYTE_NOLEN;
201
b5445a23 202 return sv_2pvbyte(sv, NULL);
cb2f1b7b
NC
203}
204
205/*
206=for apidoc sv_2pvutf8_nolen
207
208Return a pointer to the UTF-8-encoded representation of the SV.
209May cause the SV to be upgraded to UTF-8 as a side-effect.
210
211Usually accessed via the C<SvPVutf8_nolen> macro.
212
213=cut
214*/
215
216char *
5aaab254 217Perl_sv_2pvutf8_nolen(pTHX_ SV *sv)
cb2f1b7b 218{
7918f24d
NC
219 PERL_ARGS_ASSERT_SV_2PVUTF8_NOLEN;
220
b5445a23 221 return sv_2pvutf8(sv, NULL);
cb2f1b7b
NC
222}
223
224/*
5abc721d
NC
225=for apidoc sv_force_normal
226
227Undo various types of fakery on an SV: if the PV is a shared string, make
228a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
796b6530 229an C<xpvmg>. See also C<L</sv_force_normal_flags>>.
5abc721d
NC
230
231=cut
232*/
233
234void
5aaab254 235Perl_sv_force_normal(pTHX_ SV *sv)
5abc721d 236{
7918f24d
NC
237 PERL_ARGS_ASSERT_SV_FORCE_NORMAL;
238
5abc721d
NC
239 sv_force_normal_flags(sv, 0);
240}
7ee2227d
SP
241
242/* sv_setsv() is now a macro using Perl_sv_setsv_flags();
243 * this function provided for binary compatibility only
244 */
245
246void
37ee558d 247Perl_sv_setsv(pTHX_ SV *dsv, SV *ssv)
7ee2227d 248{
7918f24d
NC
249 PERL_ARGS_ASSERT_SV_SETSV;
250
37ee558d 251 sv_setsv_flags(dsv, ssv, SV_GMAGIC);
7ee2227d
SP
252}
253
254/* sv_catpvn() is now a macro using Perl_sv_catpvn_flags();
255 * this function provided for binary compatibility only
256 */
257
258void
259Perl_sv_catpvn(pTHX_ SV *dsv, const char* sstr, STRLEN slen)
260{
7918f24d
NC
261 PERL_ARGS_ASSERT_SV_CATPVN;
262
7ee2227d
SP
263 sv_catpvn_flags(dsv, sstr, slen, SV_GMAGIC);
264}
265
b347df82 266void
37ee558d 267Perl_sv_catpvn_mg(pTHX_ SV *dsv, const char *sstr, STRLEN len)
b347df82 268{
7918f24d
NC
269 PERL_ARGS_ASSERT_SV_CATPVN_MG;
270
37ee558d 271 sv_catpvn_flags(dsv,sstr,len,SV_GMAGIC|SV_SMAGIC);
b347df82
NC
272}
273
7ee2227d
SP
274/* sv_catsv() is now a macro using Perl_sv_catsv_flags();
275 * this function provided for binary compatibility only
276 */
277
278void
37ee558d 279Perl_sv_catsv(pTHX_ SV *dsv, SV *sstr)
7ee2227d 280{
7918f24d
NC
281 PERL_ARGS_ASSERT_SV_CATSV;
282
37ee558d 283 sv_catsv_flags(dsv, sstr, SV_GMAGIC);
7ee2227d
SP
284}
285
0feed65a 286/*
b347df82
NC
287=for apidoc sv_catsv_mg
288
289Like C<sv_catsv>, but also handles 'set' magic.
290
291=cut
292*/
293
294void
37ee558d 295Perl_sv_catsv_mg(pTHX_ SV *dsv, SV *sstr)
b347df82 296{
7918f24d
NC
297 PERL_ARGS_ASSERT_SV_CATSV_MG;
298
37ee558d 299 sv_catsv_flags(dsv,sstr,SV_GMAGIC|SV_SMAGIC);
b347df82
NC
300}
301
302/*
0feed65a
NC
303=for apidoc sv_iv
304
305A private implementation of the C<SvIVx> macro for compilers which can't
72d33970 306cope with complex macro expressions. Always use the macro instead.
0feed65a
NC
307
308=cut
309*/
310
311IV
5aaab254 312Perl_sv_iv(pTHX_ SV *sv)
0feed65a 313{
7918f24d
NC
314 PERL_ARGS_ASSERT_SV_IV;
315
0feed65a
NC
316 if (SvIOK(sv)) {
317 if (SvIsUV(sv))
318 return (IV)SvUVX(sv);
319 return SvIVX(sv);
320 }
321 return sv_2iv(sv);
322}
323
324/*
325=for apidoc sv_uv
326
327A private implementation of the C<SvUVx> macro for compilers which can't
72d33970 328cope with complex macro expressions. Always use the macro instead.
0feed65a
NC
329
330=cut
331*/
332
333UV
5aaab254 334Perl_sv_uv(pTHX_ SV *sv)
0feed65a 335{
7918f24d
NC
336 PERL_ARGS_ASSERT_SV_UV;
337
0feed65a
NC
338 if (SvIOK(sv)) {
339 if (SvIsUV(sv))
340 return SvUVX(sv);
341 return (UV)SvIVX(sv);
342 }
343 return sv_2uv(sv);
344}
345
346/*
347=for apidoc sv_nv
348
349A private implementation of the C<SvNVx> macro for compilers which can't
72d33970 350cope with complex macro expressions. Always use the macro instead.
0feed65a
NC
351
352=cut
353*/
354
355NV
5aaab254 356Perl_sv_nv(pTHX_ SV *sv)
0feed65a 357{
7918f24d
NC
358 PERL_ARGS_ASSERT_SV_NV;
359
0feed65a
NC
360 if (SvNOK(sv))
361 return SvNVX(sv);
362 return sv_2nv(sv);
363}
364
365/*
366=for apidoc sv_pv
367
368Use the C<SvPV_nolen> macro instead
369
370=for apidoc sv_pvn
371
372A private implementation of the C<SvPV> macro for compilers which can't
72d33970 373cope with complex macro expressions. Always use the macro instead.
0feed65a
NC
374
375=cut
376*/
377
378char *
379Perl_sv_pvn(pTHX_ SV *sv, STRLEN *lp)
380{
7918f24d
NC
381 PERL_ARGS_ASSERT_SV_PVN;
382
0feed65a
NC
383 if (SvPOK(sv)) {
384 *lp = SvCUR(sv);
385 return SvPVX(sv);
386 }
387 return sv_2pv(sv, lp);
388}
389
390
391char *
5aaab254 392Perl_sv_pvn_nomg(pTHX_ SV *sv, STRLEN *lp)
0feed65a 393{
7918f24d
NC
394 PERL_ARGS_ASSERT_SV_PVN_NOMG;
395
0feed65a
NC
396 if (SvPOK(sv)) {
397 *lp = SvCUR(sv);
398 return SvPVX(sv);
399 }
400 return sv_2pv_flags(sv, lp, 0);
401}
402
7ee2227d
SP
403/* sv_pv() is now a macro using SvPV_nolen();
404 * this function provided for binary compatibility only
405 */
406
407char *
408Perl_sv_pv(pTHX_ SV *sv)
409{
7918f24d
NC
410 PERL_ARGS_ASSERT_SV_PV;
411
7ee2227d
SP
412 if (SvPOK(sv))
413 return SvPVX(sv);
414
b5445a23 415 return sv_2pv(sv, NULL);
7ee2227d
SP
416}
417
418/* sv_pvn_force() is now a macro using Perl_sv_pvn_force_flags();
419 * this function provided for binary compatibility only
420 */
421
422char *
423Perl_sv_pvn_force(pTHX_ SV *sv, STRLEN *lp)
424{
7918f24d
NC
425 PERL_ARGS_ASSERT_SV_PVN_FORCE;
426
7ee2227d
SP
427 return sv_pvn_force_flags(sv, lp, SV_GMAGIC);
428}
429
430/* sv_pvbyte () is now a macro using Perl_sv_2pv_flags();
431 * this function provided for binary compatibility only
432 */
433
434char *
435Perl_sv_pvbyte(pTHX_ SV *sv)
436{
7918f24d
NC
437 PERL_ARGS_ASSERT_SV_PVBYTE;
438
b5445a23 439 sv_utf8_downgrade(sv, FALSE);
7ee2227d
SP
440 return sv_pv(sv);
441}
442
0feed65a
NC
443/*
444=for apidoc sv_pvbyte
445
446Use C<SvPVbyte_nolen> instead.
447
448=for apidoc sv_pvbyten
449
450A private implementation of the C<SvPVbyte> macro for compilers
72d33970 451which can't cope with complex macro expressions. Always use the macro
0feed65a
NC
452instead.
453
454=cut
455*/
456
457char *
458Perl_sv_pvbyten(pTHX_ SV *sv, STRLEN *lp)
459{
7918f24d
NC
460 PERL_ARGS_ASSERT_SV_PVBYTEN;
461
b5445a23 462 sv_utf8_downgrade(sv, FALSE);
0feed65a
NC
463 return sv_pvn(sv,lp);
464}
465
7ee2227d
SP
466/* sv_pvutf8 () is now a macro using Perl_sv_2pv_flags();
467 * this function provided for binary compatibility only
468 */
469
470char *
471Perl_sv_pvutf8(pTHX_ SV *sv)
472{
7918f24d
NC
473 PERL_ARGS_ASSERT_SV_PVUTF8;
474
7ee2227d
SP
475 sv_utf8_upgrade(sv);
476 return sv_pv(sv);
477}
478
0feed65a
NC
479/*
480=for apidoc sv_pvutf8
481
482Use the C<SvPVutf8_nolen> macro instead
483
484=for apidoc sv_pvutf8n
485
486A private implementation of the C<SvPVutf8> macro for compilers
72d33970 487which can't cope with complex macro expressions. Always use the macro
0feed65a
NC
488instead.
489
490=cut
491*/
492
493char *
494Perl_sv_pvutf8n(pTHX_ SV *sv, STRLEN *lp)
495{
7918f24d
NC
496 PERL_ARGS_ASSERT_SV_PVUTF8N;
497
0feed65a
NC
498 sv_utf8_upgrade(sv);
499 return sv_pvn(sv,lp);
500}
501
205c02c2
NC
502/* sv_utf8_upgrade() is now a macro using sv_utf8_upgrade_flags();
503 * this function provided for binary compatibility only
504 */
505
506STRLEN
5aaab254 507Perl_sv_utf8_upgrade(pTHX_ SV *sv)
205c02c2 508{
7918f24d
NC
509 PERL_ARGS_ASSERT_SV_UTF8_UPGRADE;
510
205c02c2
NC
511 return sv_utf8_upgrade_flags(sv, SV_GMAGIC);
512}
513
7ee2227d
SP
514int
515Perl_fprintf_nocontext(PerlIO *stream, const char *format, ...)
516{
3ed3a8af 517 int ret = 0;
fc917fff 518 va_list arglist;
7918f24d
NC
519
520 /* Easier to special case this here than in embed.pl. (Look at what it
521 generates for proto.h) */
522#ifdef PERL_IMPLICIT_CONTEXT
523 PERL_ARGS_ASSERT_FPRINTF_NOCONTEXT;
524#endif
525
7ee2227d 526 va_start(arglist, format);
3ed3a8af
JH
527 ret = PerlIO_vprintf(stream, format, arglist);
528 va_end(arglist);
529 return ret;
7ee2227d
SP
530}
531
532int
533Perl_printf_nocontext(const char *format, ...)
534{
535 dTHX;
fc917fff 536 va_list arglist;
3ed3a8af 537 int ret = 0;
7918f24d
NC
538
539#ifdef PERL_IMPLICIT_CONTEXT
540 PERL_ARGS_ASSERT_PRINTF_NOCONTEXT;
541#endif
542
7ee2227d 543 va_start(arglist, format);
3ed3a8af
JH
544 ret = PerlIO_vprintf(PerlIO_stdout(), format, arglist);
545 va_end(arglist);
546 return ret;
7ee2227d
SP
547}
548
549#if defined(HUGE_VAL) || (defined(USE_LONG_DOUBLE) && defined(HUGE_VALL))
550/*
551 * This hack is to force load of "huge" support from libm.a
552 * So it is in perl for (say) POSIX to use.
553 * Needed for SunOS with Sun's 'acc' for example.
554 */
555NV
556Perl_huge(void)
557{
c773ee7a 558# if defined(USE_LONG_DOUBLE) && defined(HUGE_VALL)
7ee2227d 559 return HUGE_VALL;
c773ee7a 560# else
7ee2227d 561 return HUGE_VAL;
c773ee7a 562# endif
7ee2227d
SP
563}
564#endif
565
f2f0f092
NC
566/* compatibility with versions <= 5.003. */
567void
568Perl_gv_fullname(pTHX_ SV *sv, const GV *gv)
569{
7918f24d
NC
570 PERL_ARGS_ASSERT_GV_FULLNAME;
571
666ea192 572 gv_fullname3(sv, gv, sv == (const SV*)gv ? "*" : "");
f2f0f092
NC
573}
574
575/* compatibility with versions <= 5.003. */
576void
577Perl_gv_efullname(pTHX_ SV *sv, const GV *gv)
578{
7918f24d
NC
579 PERL_ARGS_ASSERT_GV_EFULLNAME;
580
666ea192 581 gv_efullname3(sv, gv, sv == (const SV*)gv ? "*" : "");
f2f0f092
NC
582}
583
2674aeec
NC
584void
585Perl_gv_fullname3(pTHX_ SV *sv, const GV *gv, const char *prefix)
586{
7918f24d
NC
587 PERL_ARGS_ASSERT_GV_FULLNAME3;
588
2674aeec
NC
589 gv_fullname4(sv, gv, prefix, TRUE);
590}
591
592void
593Perl_gv_efullname3(pTHX_ SV *sv, const GV *gv, const char *prefix)
594{
7918f24d
NC
595 PERL_ARGS_ASSERT_GV_EFULLNAME3;
596
2674aeec
NC
597 gv_efullname4(sv, gv, prefix, TRUE);
598}
599
887986eb 600/*
3f620621 601=for apidoc_section $GV
887986eb
NC
602=for apidoc gv_fetchmethod
603
ca8b95d7 604See L</gv_fetchmethod_autoload>.
887986eb
NC
605
606=cut
607*/
608
609GV *
610Perl_gv_fetchmethod(pTHX_ HV *stash, const char *name)
611{
7918f24d
NC
612 PERL_ARGS_ASSERT_GV_FETCHMETHOD;
613
887986eb
NC
614 return gv_fetchmethod_autoload(stash, name, TRUE);
615}
616
7a7b9979
NC
617HE *
618Perl_hv_iternext(pTHX_ HV *hv)
619{
7918f24d
NC
620 PERL_ARGS_ASSERT_HV_ITERNEXT;
621
7a7b9979
NC
622 return hv_iternext_flags(hv, 0);
623}
624
bc5cdc23
NC
625void
626Perl_hv_magic(pTHX_ HV *hv, GV *gv, int how)
627{
7918f24d
NC
628 PERL_ARGS_ASSERT_HV_MAGIC;
629
ad64d0ec 630 sv_magic(MUTABLE_SV(hv), MUTABLE_SV(gv), how, NULL, 0);
bc5cdc23
NC
631}
632
34d367cd 633bool
5aaab254 634Perl_do_open(pTHX_ GV *gv, const char *name, I32 len, int as_raw,
e4dba786
NC
635 int rawmode, int rawperm, PerlIO *supplied_fp)
636{
7918f24d
NC
637 PERL_ARGS_ASSERT_DO_OPEN;
638
e4dba786
NC
639 return do_openn(gv, name, len, as_raw, rawmode, rawperm,
640 supplied_fp, (SV **) NULL, 0);
641}
642
643bool
5aaab254 644Perl_do_open9(pTHX_ GV *gv, const char *name, I32 len, int
34d367cd
SP
645as_raw,
646 int rawmode, int rawperm, PerlIO *supplied_fp, SV *svs,
647 I32 num_svs)
648{
7918f24d
NC
649 PERL_ARGS_ASSERT_DO_OPEN9;
650
34d367cd
SP
651 PERL_UNUSED_ARG(num_svs);
652 return do_openn(gv, name, len, as_raw, rawmode, rawperm,
653 supplied_fp, &svs, 1);
654}
655
656int
657Perl_do_binmode(pTHX_ PerlIO *fp, int iotype, int mode)
658{
659 /* The old body of this is now in non-LAYER part of perlio.c
660 * This is a stub for any XS code which might have been calling it.
661 */
662 const char *name = ":raw";
7918f24d
NC
663
664 PERL_ARGS_ASSERT_DO_BINMODE;
665
34d367cd
SP
666#ifdef PERLIO_USING_CRLF
667 if (!(mode & O_BINARY))
668 name = ":crlf";
669#endif
670 return PerlIO_binmode(aTHX_ fp, iotype, mode, name);
671}
672
a9f96b3f
NC
673#ifndef OS2
674bool
5aaab254 675Perl_do_aexec(pTHX_ SV *really, SV **mark, SV **sp)
a9f96b3f 676{
7918f24d
NC
677 PERL_ARGS_ASSERT_DO_AEXEC;
678
a9f96b3f
NC
679 return do_aexec5(really, mark, sp, 0, 0);
680}
681#endif
682
89552e80
NC
683/* Backwards compatibility. */
684int
685Perl_init_i18nl14n(pTHX_ int printwarn)
686{
687 return init_i18nl10n(printwarn);
688}
689
814fafa7 690bool
c41b2540 691Perl_is_utf8_string_loc(const U8 *s, const STRLEN len, const U8 **ep)
814fafa7 692{
7918f24d
NC
693 PERL_ARGS_ASSERT_IS_UTF8_STRING_LOC;
694
814fafa7
NC
695 return is_utf8_string_loclen(s, len, ep, 0);
696}
697
7ee2227d 698/*
3f620621 699=for apidoc_section $SV
d5b2b27b
NC
700=for apidoc sv_nolocking
701
702Dummy routine which "locks" an SV when there is no locking module present.
796b6530 703Exists to avoid test for a C<NULL> function pointer and because it could
d5b2b27b
NC
704potentially warn under some level of strict-ness.
705
796b6530 706"Superseded" by C<sv_nosharing()>.
d5b2b27b
NC
707
708=cut
709*/
710
711void
712Perl_sv_nolocking(pTHX_ SV *sv)
713{
96a5add6 714 PERL_UNUSED_CONTEXT;
d5b2b27b
NC
715 PERL_UNUSED_ARG(sv);
716}
717
718
719/*
720=for apidoc sv_nounlocking
721
722Dummy routine which "unlocks" an SV when there is no locking module present.
796b6530 723Exists to avoid test for a C<NULL> function pointer and because it could
d5b2b27b
NC
724potentially warn under some level of strict-ness.
725
796b6530 726"Superseded" by C<sv_nosharing()>.
d5b2b27b
NC
727
728=cut
af50ae69
KW
729
730PERL_UNLOCK_HOOK in intrpvar.h is the macro that refers to this, and guarantees
731that mathoms gets loaded.
732
d5b2b27b
NC
733*/
734
735void
736Perl_sv_nounlocking(pTHX_ SV *sv)
737{
96a5add6 738 PERL_UNUSED_CONTEXT;
d5b2b27b
NC
739 PERL_UNUSED_ARG(sv);
740}
741
2053acbf
NC
742void
743Perl_save_long(pTHX_ long int *longp)
744{
7918f24d
NC
745 PERL_ARGS_ASSERT_SAVE_LONG;
746
2053acbf
NC
747 SSCHECK(3);
748 SSPUSHLONG(*longp);
749 SSPUSHPTR(longp);
c6bf6a65 750 SSPUSHUV(SAVEt_LONG);
2053acbf
NC
751}
752
753void
2053acbf
NC
754Perl_save_nogv(pTHX_ GV *gv)
755{
7918f24d
NC
756 PERL_ARGS_ASSERT_SAVE_NOGV;
757
2053acbf
NC
758 SSCHECK(2);
759 SSPUSHPTR(gv);
c6bf6a65 760 SSPUSHUV(SAVEt_NSTAB);
2053acbf
NC
761}
762
763void
5aaab254 764Perl_save_list(pTHX_ SV **sarg, I32 maxsarg)
2053acbf 765{
eb578fdb 766 I32 i;
2053acbf 767
7918f24d
NC
768 PERL_ARGS_ASSERT_SAVE_LIST;
769
2053acbf 770 for (i = 1; i <= maxsarg; i++) {
3ed356df
FC
771 SV *sv;
772 SvGETMAGIC(sarg[i]);
773 sv = newSV(0);
774 sv_setsv_nomg(sv,sarg[i]);
2053acbf
NC
775 SSCHECK(3);
776 SSPUSHPTR(sarg[i]); /* remember the pointer */
777 SSPUSHPTR(sv); /* remember the value */
c6bf6a65 778 SSPUSHUV(SAVEt_ITEM);
2053acbf
NC
779 }
780}
781
47518d95
NC
782/*
783=for apidoc sv_usepvn_mg
784
785Like C<sv_usepvn>, but also handles 'set' magic.
786
787=cut
788*/
789
790void
791Perl_sv_usepvn_mg(pTHX_ SV *sv, char *ptr, STRLEN len)
792{
7918f24d
NC
793 PERL_ARGS_ASSERT_SV_USEPVN_MG;
794
47518d95
NC
795 sv_usepvn_flags(sv,ptr,len, SV_SMAGIC);
796}
797
798/*
799=for apidoc sv_usepvn
800
72d33970 801Tells an SV to use C<ptr> to find its string value. Implemented by
47518d95 802calling C<sv_usepvn_flags> with C<flags> of 0, hence does not handle 'set'
fbe13c60 803magic. See C<L</sv_usepvn_flags>>.
47518d95
NC
804
805=cut
806*/
807
808void
809Perl_sv_usepvn(pTHX_ SV *sv, char *ptr, STRLEN len)
810{
7918f24d
NC
811 PERL_ARGS_ASSERT_SV_USEPVN;
812
47518d95
NC
813 sv_usepvn_flags(sv,ptr,len, 0);
814}
815
c03e83bf 816/*
3f620621 817=for apidoc_section $pack
c03e83bf
NC
818=for apidoc unpack_str
819
796b6530
KW
820The engine implementing C<unpack()> Perl function. Note: parameters C<strbeg>,
821C<new_s> and C<ocnt> are not used. This call should not be used, use
822C<unpackstring> instead.
c03e83bf
NC
823
824=cut */
825
e1b825c1 826SSize_t
c03e83bf
NC
827Perl_unpack_str(pTHX_ const char *pat, const char *patend, const char *s,
828 const char *strbeg, const char *strend, char **new_s, I32 ocnt,
829 U32 flags)
830{
7918f24d
NC
831 PERL_ARGS_ASSERT_UNPACK_STR;
832
c03e83bf
NC
833 PERL_UNUSED_ARG(strbeg);
834 PERL_UNUSED_ARG(new_s);
835 PERL_UNUSED_ARG(ocnt);
836
837 return unpackstring(pat, patend, s, strend, flags);
838}
b47163a2
NC
839
840/*
841=for apidoc pack_cat
842
796b6530
KW
843The engine implementing C<pack()> Perl function. Note: parameters
844C<next_in_list> and C<flags> are not used. This call should not be used; use
550697d6 845C<L</packlist>> instead.
b47163a2
NC
846
847=cut
848*/
849
850void
5aaab254 851Perl_pack_cat(pTHX_ SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags)
b47163a2 852{
7918f24d
NC
853 PERL_ARGS_ASSERT_PACK_CAT;
854
b47163a2
NC
855 PERL_UNUSED_ARG(next_in_list);
856 PERL_UNUSED_ARG(flags);
857
858 packlist(cat, pat, patend, beglist, endlist);
859}
4c2df08c
NC
860
861HE *
862Perl_hv_store_ent(pTHX_ HV *hv, SV *keysv, SV *val, U32 hash)
863{
59af68cc 864 return (HE *)hv_common(hv, keysv, NULL, 0, 0, HV_FETCH_ISSTORE, val, hash);
4c2df08c
NC
865}
866
867bool
868Perl_hv_exists_ent(pTHX_ HV *hv, SV *keysv, U32 hash)
869{
7918f24d
NC
870 PERL_ARGS_ASSERT_HV_EXISTS_ENT;
871
8298454c 872 return cBOOL(hv_common(hv, keysv, NULL, 0, 0, HV_FETCH_ISEXISTS, 0, hash));
4c2df08c
NC
873}
874
875HE *
876Perl_hv_fetch_ent(pTHX_ HV *hv, SV *keysv, I32 lval, U32 hash)
877{
7918f24d
NC
878 PERL_ARGS_ASSERT_HV_FETCH_ENT;
879
59af68cc 880 return (HE *)hv_common(hv, keysv, NULL, 0, 0,
4c2df08c
NC
881 (lval ? HV_FETCH_LVALUE : 0), NULL, hash);
882}
883
884SV *
885Perl_hv_delete_ent(pTHX_ HV *hv, SV *keysv, I32 flags, U32 hash)
886{
7918f24d
NC
887 PERL_ARGS_ASSERT_HV_DELETE_ENT;
888
ad64d0ec
NC
889 return MUTABLE_SV(hv_common(hv, keysv, NULL, 0, 0, flags | HV_DELETE, NULL,
890 hash));
4c2df08c
NC
891}
892
a038e571
NC
893SV**
894Perl_hv_store_flags(pTHX_ HV *hv, const char *key, I32 klen, SV *val, U32 hash,
895 int flags)
896{
897 return (SV**) hv_common(hv, NULL, key, klen, flags,
898 (HV_FETCH_ISSTORE|HV_FETCH_JUST_SV), val, hash);
899}
900
901SV**
902Perl_hv_store(pTHX_ HV *hv, const char *key, I32 klen_i32, SV *val, U32 hash)
903{
904 STRLEN klen;
905 int flags;
906
907 if (klen_i32 < 0) {
908 klen = -klen_i32;
909 flags = HVhek_UTF8;
910 } else {
911 klen = klen_i32;
912 flags = 0;
913 }
914 return (SV **) hv_common(hv, NULL, key, klen, flags,
915 (HV_FETCH_ISSTORE|HV_FETCH_JUST_SV), val, hash);
916}
917
918bool
919Perl_hv_exists(pTHX_ HV *hv, const char *key, I32 klen_i32)
920{
921 STRLEN klen;
922 int flags;
923
7918f24d
NC
924 PERL_ARGS_ASSERT_HV_EXISTS;
925
a038e571
NC
926 if (klen_i32 < 0) {
927 klen = -klen_i32;
928 flags = HVhek_UTF8;
929 } else {
930 klen = klen_i32;
931 flags = 0;
932 }
8298454c 933 return cBOOL(hv_common(hv, NULL, key, klen, flags, HV_FETCH_ISEXISTS, 0, 0));
a038e571
NC
934}
935
936SV**
937Perl_hv_fetch(pTHX_ HV *hv, const char *key, I32 klen_i32, I32 lval)
938{
939 STRLEN klen;
940 int flags;
941
7918f24d
NC
942 PERL_ARGS_ASSERT_HV_FETCH;
943
a038e571
NC
944 if (klen_i32 < 0) {
945 klen = -klen_i32;
946 flags = HVhek_UTF8;
947 } else {
948 klen = klen_i32;
949 flags = 0;
950 }
951 return (SV **) hv_common(hv, NULL, key, klen, flags,
952 lval ? (HV_FETCH_JUST_SV | HV_FETCH_LVALUE)
953 : HV_FETCH_JUST_SV, NULL, 0);
954}
955
956SV *
957Perl_hv_delete(pTHX_ HV *hv, const char *key, I32 klen_i32, I32 flags)
958{
959 STRLEN klen;
960 int k_flags;
961
7918f24d
NC
962 PERL_ARGS_ASSERT_HV_DELETE;
963
a038e571
NC
964 if (klen_i32 < 0) {
965 klen = -klen_i32;
966 k_flags = HVhek_UTF8;
967 } else {
968 klen = klen_i32;
969 k_flags = 0;
970 }
ad64d0ec
NC
971 return MUTABLE_SV(hv_common(hv, NULL, key, klen, k_flags, flags | HV_DELETE,
972 NULL, 0));
a038e571
NC
973}
974
ac572bf4
NC
975AV *
976Perl_newAV(pTHX)
977{
502c6561 978 return MUTABLE_AV(newSV_type(SVt_PVAV));
ac572bf4
NC
979 /* sv_upgrade does AvREAL_only():
980 AvALLOC(av) = 0;
981 AvARRAY(av) = NULL;
982 AvMAX(av) = AvFILLp(av) = -1; */
983}
984
78ac7dd9
NC
985HV *
986Perl_newHV(pTHX)
987{
85fbaab2 988 HV * const hv = MUTABLE_HV(newSV_type(SVt_PVHV));
78ac7dd9
NC
989 assert(!SvOK(hv));
990
991 return hv;
992}
993
84335ee9
NC
994void
995Perl_sv_insert(pTHX_ SV *const bigstr, const STRLEN offset, const STRLEN len,
996 const char *const little, const STRLEN littlelen)
997{
998 PERL_ARGS_ASSERT_SV_INSERT;
999 sv_insert_flags(bigstr, offset, len, little, littlelen, SV_GMAGIC);
1000}
1001
2fd8beea
NC
1002void
1003Perl_save_freesv(pTHX_ SV *sv)
1004{
2fd8beea
NC
1005 save_freesv(sv);
1006}
1007
1008void
1009Perl_save_mortalizesv(pTHX_ SV *sv)
1010{
2fd8beea
NC
1011 PERL_ARGS_ASSERT_SAVE_MORTALIZESV;
1012
1013 save_mortalizesv(sv);
1014}
1015
1016void
1017Perl_save_freeop(pTHX_ OP *o)
1018{
2fd8beea
NC
1019 save_freeop(o);
1020}
1021
1022void
1023Perl_save_freepv(pTHX_ char *pv)
1024{
2fd8beea
NC
1025 save_freepv(pv);
1026}
1027
1028void
1029Perl_save_op(pTHX)
1030{
2fd8beea
NC
1031 save_op();
1032}
1033
d5713896
NC
1034#ifdef PERL_DONT_CREATE_GVSV
1035GV *
1036Perl_gv_SVadd(pTHX_ GV *gv)
1037{
d5713896
NC
1038 return gv_SVadd(gv);
1039}
1040#endif
1041
1042GV *
1043Perl_gv_AVadd(pTHX_ GV *gv)
1044{
d5713896
NC
1045 return gv_AVadd(gv);
1046}
1047
1048GV *
5aaab254 1049Perl_gv_HVadd(pTHX_ GV *gv)
d5713896 1050{
d5713896
NC
1051 return gv_HVadd(gv);
1052}
1053
bb85b28a 1054GV *
5aaab254 1055Perl_gv_IOadd(pTHX_ GV *gv)
bb85b28a
NC
1056{
1057 return gv_IOadd(gv);
1058}
1059
85dca89a
NC
1060IO *
1061Perl_newIO(pTHX)
1062{
1063 return MUTABLE_IO(newSV_type(SVt_PVIO));
1064}
1065
0d7d409d
DM
1066I32
1067Perl_my_stat(pTHX)
1068{
1069 return my_stat_flags(SV_GMAGIC);
1070}
1071
1072I32
1073Perl_my_lstat(pTHX)
1074{
1075 return my_lstat_flags(SV_GMAGIC);
1076}
1077
078504b2 1078I32
5aaab254 1079Perl_sv_eq(pTHX_ SV *sv1, SV *sv2)
078504b2
FC
1080{
1081 return sv_eq_flags(sv1, sv2, SV_GMAGIC);
1082}
1083
6129b56c 1084#ifdef USE_LOCALE_COLLATE
078504b2
FC
1085char *
1086Perl_sv_collxfrm(pTHX_ SV *const sv, STRLEN *const nxp)
1087{
1545ba5b 1088 PERL_ARGS_ASSERT_SV_COLLXFRM;
078504b2
FC
1089 return sv_collxfrm_flags(sv, nxp, SV_GMAGIC);
1090}
78d57975
KW
1091
1092char *
1093Perl_mem_collxfrm(pTHX_ const char *input_string, STRLEN len, STRLEN *xlen)
1094{
1095 /* This function is retained for compatibility in case someone outside core
1096 * is using this (but it is undocumented) */
1097
1098 PERL_ARGS_ASSERT_MEM_COLLXFRM;
1099
1100 return _mem_collxfrm(input_string, len, xlen, FALSE);
1101}
1102
6129b56c 1103#endif
078504b2 1104
06c841cf 1105bool
5aaab254 1106Perl_sv_2bool(pTHX_ SV *const sv)
06c841cf 1107{
1545ba5b 1108 PERL_ARGS_ASSERT_SV_2BOOL;
06c841cf
FC
1109 return sv_2bool_flags(sv, SV_GMAGIC);
1110}
1111
1830b3d9 1112
9733086d 1113/*
3f620621 1114=for apidoc_section $custom
9733086d 1115=for apidoc custom_op_name
796b6530 1116Return the name for a given custom op. This was once used by the C<OP_NAME>
9733086d
BM
1117macro, but is no longer: it has only been kept for compatibility, and
1118should not be used.
1119
1120=for apidoc custom_op_desc
72d33970 1121Return the description of a given custom op. This was once used by the
796b6530 1122C<OP_DESC> macro, but is no longer: it has only been kept for
9733086d
BM
1123compatibility, and should not be used.
1124
1125=cut
1126*/
1127
1830b3d9
BM
1128const char*
1129Perl_custom_op_name(pTHX_ const OP* o)
1130{
1131 PERL_ARGS_ASSERT_CUSTOM_OP_NAME;
ae103e09 1132 return XopENTRYCUSTOM(o, xop_name);
1830b3d9
BM
1133}
1134
1135const char*
1136Perl_custom_op_desc(pTHX_ const OP* o)
1137{
1138 PERL_ARGS_ASSERT_CUSTOM_OP_DESC;
ae103e09 1139 return XopENTRYCUSTOM(o, xop_desc);
1830b3d9 1140}
7bff8c33
NC
1141
1142CV *
1143Perl_newSUB(pTHX_ I32 floor, OP *o, OP *proto, OP *block)
1144{
e8f91c91 1145 return newATTRSUB(floor, o, proto, NULL, block);
7bff8c33 1146}
0c9b0438 1147
108cb980 1148SV *
37ee558d 1149Perl_sv_mortalcopy(pTHX_ SV *const oldsv)
108cb980 1150{
37ee558d 1151 return Perl_sv_mortalcopy_flags(aTHX_ oldsv, SV_GMAGIC);
108cb980
FC
1152}
1153
e4524c4c
DD
1154void
1155Perl_sv_copypv(pTHX_ SV *const dsv, SV *const ssv)
1156{
1157 PERL_ARGS_ASSERT_SV_COPYPV;
1158
6338d1c6 1159 sv_copypv_flags(dsv, ssv, SV_GMAGIC);
e4524c4c
DD
1160}
1161
3d81eea6
KW
1162UV /* Made into a function, so can be deprecated */
1163NATIVE_TO_NEED(const UV enc, const UV ch)
1164{
1165 PERL_UNUSED_ARG(enc);
1166 return ch;
1167}
1168
1169UV /* Made into a function, so can be deprecated */
1170ASCII_TO_NEED(const UV enc, const UV ch)
1171{
1172 PERL_UNUSED_ARG(enc);
1173 return ch;
1174}
1175
f2645549 1176/*
3f620621 1177=for apidoc_section $unicode
f2645549
KW
1178=for apidoc is_utf8_char
1179
1180Tests if some arbitrary number of bytes begins in a valid UTF-8
1181character. Note that an INVARIANT (i.e. ASCII on non-EBCDIC machines)
1182character is a valid UTF-8 character. The actual number of bytes in the UTF-8
1183character will be returned if it is valid, otherwise 0.
1184
1185This function is deprecated due to the possibility that malformed input could
1186cause reading beyond the end of the input buffer. Use L</isUTF8_CHAR>
1187instead.
1188
1189=cut */
1190
1191STRLEN
1192Perl_is_utf8_char(const U8 *s)
1193{
1194 PERL_ARGS_ASSERT_IS_UTF8_CHAR;
1195
c6734c35 1196 /* Assumes we have enough space, which is why this is deprecated. But the
00e53078
KW
1197 * UTF8_CHK_SKIP(s)) makes it safe for the common case of NUL-terminated
1198 * strings */
1199 return isUTF8_CHAR(s, s + UTF8_CHK_SKIP(s));
f2645549
KW
1200}
1201
e4524c4c
DD
1202/*
1203=for apidoc is_utf8_char_buf
1204
09232555 1205This is identical to the macro L<perlapi/isUTF8_CHAR>.
e4524c4c
DD
1206
1207=cut */
1208
1209STRLEN
1210Perl_is_utf8_char_buf(const U8 *buf, const U8* buf_end)
1211{
1212
1213 PERL_ARGS_ASSERT_IS_UTF8_CHAR_BUF;
1214
1215 return isUTF8_CHAR(buf, buf_end);
1216}
1217
f2645549
KW
1218/* DEPRECATED!
1219 * Like L</utf8_to_uvuni_buf>(), but should only be called when it is known that
1220 * there are no malformations in the input UTF-8 string C<s>. Surrogates,
1221 * non-character code points, and non-Unicode code points are allowed */
1222
1223UV
1224Perl_valid_utf8_to_uvuni(pTHX_ const U8 *s, STRLEN *retlen)
1225{
e9b8343f 1226 PERL_UNUSED_CONTEXT;
f2645549
KW
1227 PERL_ARGS_ASSERT_VALID_UTF8_TO_UVUNI;
1228
1229 return NATIVE_TO_UNI(valid_utf8_to_uvchr(s, retlen));
1230}
1231
1232/*
f2645549
KW
1233=for apidoc utf8_to_uvuni
1234
1235Returns the Unicode code point of the first character in the string C<s>
1236which is assumed to be in UTF-8 encoding; C<retlen> will be set to the
1237length, in bytes, of that character.
1238
1239Some, but not all, UTF-8 malformations are detected, and in fact, some
1240malformed input could cause reading beyond the end of the input buffer, which
1241is one reason why this function is deprecated. The other is that only in
1242extremely limited circumstances should the Unicode versus native code point be
1243of any interest to you. See L</utf8_to_uvuni_buf> for alternatives.
1244
1245If C<s> points to one of the detected malformations, and UTF8 warnings are
1246enabled, zero is returned and C<*retlen> is set (if C<retlen> doesn't point to
1247NULL) to -1. If those warnings are off, the computed value if well-defined (or
1248the Unicode REPLACEMENT CHARACTER, if not) is silently returned, and C<*retlen>
1249is set (if C<retlen> isn't NULL) so that (S<C<s> + C<*retlen>>) is the
1250next possible position in C<s> that could begin a non-malformed character.
09232555 1251See L<perlapi/utf8n_to_uvchr> for details on when the REPLACEMENT CHARACTER is returned.
f2645549
KW
1252
1253=cut
1254*/
1255
1256UV
1257Perl_utf8_to_uvuni(pTHX_ const U8 *s, STRLEN *retlen)
1258{
e9b8343f 1259 PERL_UNUSED_CONTEXT;
f2645549
KW
1260 PERL_ARGS_ASSERT_UTF8_TO_UVUNI;
1261
1262 return NATIVE_TO_UNI(valid_utf8_to_uvchr(s, retlen));
1263}
1264
09d7a3ba 1265/*
44170c9a 1266=for apidoc pad_compname_type
09d7a3ba 1267
2d7f6611 1268Looks up the type of the lexical variable at position C<po> in the
09d7a3ba
FC
1269currently-compiling pad. If the variable is typed, the stash of the
1270class to which it is typed is returned. If not, C<NULL> is returned.
1271
1272=cut
1273*/
1274
1275HV *
1276Perl_pad_compname_type(pTHX_ const PADOFFSET po)
1277{
1278 return PAD_COMPNAME_TYPE(po);
1279}
1280
534dad48 1281/* return ptr to little string in big string, NULL if not found */
fb245905 1282/* The original version of this routine was donated by Corey Satten. */
534dad48
CB
1283
1284char *
1285Perl_instr(const char *big, const char *little)
1286{
534dad48 1287 PERL_ARGS_ASSERT_INSTR;
534dad48 1288
4e528812 1289 return instr(big, little);
534dad48 1290}
0ddd4a5b 1291
238f2c13
P
1292SV *
1293Perl_newSVsv(pTHX_ SV *const old)
1294{
1295 return newSVsv(old);
1296}
1297
423ce623
P
1298bool
1299Perl_sv_utf8_downgrade(pTHX_ SV *const sv, const bool fail_ok)
1300{
1301 PERL_ARGS_ASSERT_SV_UTF8_DOWNGRADE;
1302
1303 return sv_utf8_downgrade(sv, fail_ok);
1304}
1305
757fc329
P
1306char *
1307Perl_sv_2pvutf8(pTHX_ SV *sv, STRLEN *const lp)
1308{
1309 PERL_ARGS_ASSERT_SV_2PVUTF8;
1310
1311 return sv_2pvutf8(sv, lp);
1312}
1313
1314char *
1315Perl_sv_2pvbyte(pTHX_ SV *sv, STRLEN *const lp)
1316{
1317 PERL_ARGS_ASSERT_SV_2PVBYTE;
1318
1319 return sv_2pvbyte(sv, lp);
1320}
1321
86a5062a
KW
1322U8 *
1323Perl_uvuni_to_utf8(pTHX_ U8 *d, UV uv)
1324{
1325 PERL_ARGS_ASSERT_UVUNI_TO_UTF8;
1326
1327 return uvoffuni_to_utf8_flags(d, uv, 0);
1328}
1329
1330/*
1331=for apidoc utf8n_to_uvuni
1332
1333Instead use L<perlapi/utf8_to_uvchr_buf>, or rarely, L<perlapi/utf8n_to_uvchr>.
1334
1335This function was useful for code that wanted to handle both EBCDIC and
1336ASCII platforms with Unicode properties, but starting in Perl v5.20, the
1337distinctions between the platforms have mostly been made invisible to most
1338code, so this function is quite unlikely to be what you want. If you do need
1339this precise functionality, use instead
1340C<L<NATIVE_TO_UNI(utf8_to_uvchr_buf(...))|perlapi/utf8_to_uvchr_buf>>
1341or C<L<NATIVE_TO_UNI(utf8n_to_uvchr(...))|perlapi/utf8n_to_uvchr>>.
1342
1343=cut
1344*/
1345
1346UV
1347Perl_utf8n_to_uvuni(pTHX_ const U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags)
1348{
1349 PERL_ARGS_ASSERT_UTF8N_TO_UVUNI;
1350
1351 return NATIVE_TO_UNI(utf8n_to_uvchr(s, curlen, retlen, flags));
1352}
1353
1354/*
1355=for apidoc uvuni_to_utf8_flags
1356
1357Instead you almost certainly want to use L<perlapi/uvchr_to_utf8> or
1358L<perlapi/uvchr_to_utf8_flags>.
1359
1360This function is a deprecated synonym for L</uvoffuni_to_utf8_flags>,
1361which itself, while not deprecated, should be used only in isolated
1362circumstances. These functions were useful for code that wanted to handle
1363both EBCDIC and ASCII platforms with Unicode properties, but starting in Perl
1364v5.20, the distinctions between the platforms have mostly been made invisible
1365to most code, so this function is quite unlikely to be what you want.
1366
1367=cut
1368*/
1369
1370U8 *
1371Perl_uvuni_to_utf8_flags(pTHX_ U8 *d, UV uv, UV flags)
1372{
1373 PERL_ARGS_ASSERT_UVUNI_TO_UTF8_FLAGS;
1374
1375 return uvoffuni_to_utf8_flags(d, uv, flags);
1376}
1377
1378/*
1379=for apidoc utf8_to_uvchr
1380
1381Returns the native code point of the first character in the string C<s>
1382which is assumed to be in UTF-8 encoding; C<retlen> will be set to the
1383length, in bytes, of that character.
1384
1385Some, but not all, UTF-8 malformations are detected, and in fact, some
1386malformed input could cause reading beyond the end of the input buffer, which
1387is why this function is deprecated. Use L</utf8_to_uvchr_buf> instead.
1388
1389If C<s> points to one of the detected malformations, and UTF8 warnings are
1390enabled, zero is returned and C<*retlen> is set (if C<retlen> isn't
1391C<NULL>) to -1. If those warnings are off, the computed value if well-defined (or
1392the Unicode REPLACEMENT CHARACTER, if not) is silently returned, and C<*retlen>
1393is set (if C<retlen> isn't NULL) so that (S<C<s> + C<*retlen>>) is the
1394next possible position in C<s> that could begin a non-malformed character.
1395See L</utf8n_to_uvchr> for details on when the REPLACEMENT CHARACTER is returned.
1396
1397=cut
1398*/
1399
1400UV
1401Perl_utf8_to_uvchr(pTHX_ const U8 *s, STRLEN *retlen)
1402{
1403 PERL_ARGS_ASSERT_UTF8_TO_UVCHR;
1404
1405 /* This function is unsafe if malformed UTF-8 input is given it, which is
1406 * why the function is deprecated. If the first byte of the input
1407 * indicates that there are more bytes remaining in the sequence that forms
1408 * the character than there are in the input buffer, it can read past the
1409 * end. But we can make it safe if the input string happens to be
1410 * NUL-terminated, as many strings in Perl are, by refusing to read past a
1411 * NUL, which is what UTF8_CHK_SKIP() does. A NUL indicates the start of
1412 * the next character anyway. If the input isn't NUL-terminated, the
1413 * function remains unsafe, as it always has been. */
1414
1415 return utf8_to_uvchr_buf(s, s + UTF8_CHK_SKIP(s), retlen);
1416}
1417
238965b4
KW
1418GCC_DIAG_RESTORE
1419
20fac488
GA
1420#endif /* NO_MATHOMS */
1421
d5b2b27b 1422/*
14d04a33 1423 * ex: set ts=8 sts=4 sw=4 et:
7ee2227d 1424 */