This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perlapi: Remove per-thread section; move to real scns
[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
b347df82 286void
37ee558d 287Perl_sv_catsv_mg(pTHX_ SV *dsv, SV *sstr)
b347df82 288{
7918f24d
NC
289 PERL_ARGS_ASSERT_SV_CATSV_MG;
290
37ee558d 291 sv_catsv_flags(dsv,sstr,SV_GMAGIC|SV_SMAGIC);
b347df82
NC
292}
293
294/*
0feed65a
NC
295=for apidoc sv_iv
296
297A private implementation of the C<SvIVx> macro for compilers which can't
72d33970 298cope with complex macro expressions. Always use the macro instead.
0feed65a
NC
299
300=cut
301*/
302
303IV
5aaab254 304Perl_sv_iv(pTHX_ SV *sv)
0feed65a 305{
7918f24d
NC
306 PERL_ARGS_ASSERT_SV_IV;
307
0feed65a
NC
308 if (SvIOK(sv)) {
309 if (SvIsUV(sv))
310 return (IV)SvUVX(sv);
311 return SvIVX(sv);
312 }
313 return sv_2iv(sv);
314}
315
316/*
317=for apidoc sv_uv
318
319A private implementation of the C<SvUVx> macro for compilers which can't
72d33970 320cope with complex macro expressions. Always use the macro instead.
0feed65a
NC
321
322=cut
323*/
324
325UV
5aaab254 326Perl_sv_uv(pTHX_ SV *sv)
0feed65a 327{
7918f24d
NC
328 PERL_ARGS_ASSERT_SV_UV;
329
0feed65a
NC
330 if (SvIOK(sv)) {
331 if (SvIsUV(sv))
332 return SvUVX(sv);
333 return (UV)SvIVX(sv);
334 }
335 return sv_2uv(sv);
336}
337
338/*
339=for apidoc sv_nv
340
341A private implementation of the C<SvNVx> macro for compilers which can't
72d33970 342cope with complex macro expressions. Always use the macro instead.
0feed65a
NC
343
344=cut
345*/
346
347NV
5aaab254 348Perl_sv_nv(pTHX_ SV *sv)
0feed65a 349{
7918f24d
NC
350 PERL_ARGS_ASSERT_SV_NV;
351
0feed65a
NC
352 if (SvNOK(sv))
353 return SvNVX(sv);
354 return sv_2nv(sv);
355}
356
357/*
358=for apidoc sv_pv
359
360Use the C<SvPV_nolen> macro instead
361
362=for apidoc sv_pvn
363
364A private implementation of the C<SvPV> macro for compilers which can't
72d33970 365cope with complex macro expressions. Always use the macro instead.
0feed65a
NC
366
367=cut
368*/
369
370char *
371Perl_sv_pvn(pTHX_ SV *sv, STRLEN *lp)
372{
7918f24d
NC
373 PERL_ARGS_ASSERT_SV_PVN;
374
0feed65a
NC
375 if (SvPOK(sv)) {
376 *lp = SvCUR(sv);
377 return SvPVX(sv);
378 }
379 return sv_2pv(sv, lp);
380}
381
382
383char *
5aaab254 384Perl_sv_pvn_nomg(pTHX_ SV *sv, STRLEN *lp)
0feed65a 385{
7918f24d
NC
386 PERL_ARGS_ASSERT_SV_PVN_NOMG;
387
0feed65a
NC
388 if (SvPOK(sv)) {
389 *lp = SvCUR(sv);
390 return SvPVX(sv);
391 }
392 return sv_2pv_flags(sv, lp, 0);
393}
394
7ee2227d
SP
395/* sv_pv() is now a macro using SvPV_nolen();
396 * this function provided for binary compatibility only
397 */
398
399char *
400Perl_sv_pv(pTHX_ SV *sv)
401{
7918f24d
NC
402 PERL_ARGS_ASSERT_SV_PV;
403
7ee2227d
SP
404 if (SvPOK(sv))
405 return SvPVX(sv);
406
b5445a23 407 return sv_2pv(sv, NULL);
7ee2227d
SP
408}
409
410/* sv_pvn_force() is now a macro using Perl_sv_pvn_force_flags();
411 * this function provided for binary compatibility only
412 */
413
414char *
415Perl_sv_pvn_force(pTHX_ SV *sv, STRLEN *lp)
416{
7918f24d
NC
417 PERL_ARGS_ASSERT_SV_PVN_FORCE;
418
7ee2227d
SP
419 return sv_pvn_force_flags(sv, lp, SV_GMAGIC);
420}
421
422/* sv_pvbyte () is now a macro using Perl_sv_2pv_flags();
423 * this function provided for binary compatibility only
424 */
425
426char *
427Perl_sv_pvbyte(pTHX_ SV *sv)
428{
7918f24d
NC
429 PERL_ARGS_ASSERT_SV_PVBYTE;
430
b5445a23 431 sv_utf8_downgrade(sv, FALSE);
7ee2227d
SP
432 return sv_pv(sv);
433}
434
0feed65a
NC
435/*
436=for apidoc sv_pvbyte
437
438Use C<SvPVbyte_nolen> instead.
439
440=for apidoc sv_pvbyten
441
442A private implementation of the C<SvPVbyte> macro for compilers
72d33970 443which can't cope with complex macro expressions. Always use the macro
0feed65a
NC
444instead.
445
446=cut
447*/
448
449char *
450Perl_sv_pvbyten(pTHX_ SV *sv, STRLEN *lp)
451{
7918f24d
NC
452 PERL_ARGS_ASSERT_SV_PVBYTEN;
453
b5445a23 454 sv_utf8_downgrade(sv, FALSE);
0feed65a
NC
455 return sv_pvn(sv,lp);
456}
457
7ee2227d
SP
458/* sv_pvutf8 () is now a macro using Perl_sv_2pv_flags();
459 * this function provided for binary compatibility only
460 */
461
462char *
463Perl_sv_pvutf8(pTHX_ SV *sv)
464{
7918f24d
NC
465 PERL_ARGS_ASSERT_SV_PVUTF8;
466
7ee2227d
SP
467 sv_utf8_upgrade(sv);
468 return sv_pv(sv);
469}
470
0feed65a
NC
471/*
472=for apidoc sv_pvutf8
473
474Use the C<SvPVutf8_nolen> macro instead
475
476=for apidoc sv_pvutf8n
477
478A private implementation of the C<SvPVutf8> macro for compilers
72d33970 479which can't cope with complex macro expressions. Always use the macro
0feed65a
NC
480instead.
481
482=cut
483*/
484
485char *
486Perl_sv_pvutf8n(pTHX_ SV *sv, STRLEN *lp)
487{
7918f24d
NC
488 PERL_ARGS_ASSERT_SV_PVUTF8N;
489
0feed65a
NC
490 sv_utf8_upgrade(sv);
491 return sv_pvn(sv,lp);
492}
493
205c02c2
NC
494/* sv_utf8_upgrade() is now a macro using sv_utf8_upgrade_flags();
495 * this function provided for binary compatibility only
496 */
497
498STRLEN
5aaab254 499Perl_sv_utf8_upgrade(pTHX_ SV *sv)
205c02c2 500{
7918f24d
NC
501 PERL_ARGS_ASSERT_SV_UTF8_UPGRADE;
502
205c02c2
NC
503 return sv_utf8_upgrade_flags(sv, SV_GMAGIC);
504}
505
7ee2227d
SP
506int
507Perl_fprintf_nocontext(PerlIO *stream, const char *format, ...)
508{
3ed3a8af 509 int ret = 0;
fc917fff 510 va_list arglist;
7918f24d
NC
511
512 /* Easier to special case this here than in embed.pl. (Look at what it
513 generates for proto.h) */
514#ifdef PERL_IMPLICIT_CONTEXT
515 PERL_ARGS_ASSERT_FPRINTF_NOCONTEXT;
516#endif
517
7ee2227d 518 va_start(arglist, format);
3ed3a8af
JH
519 ret = PerlIO_vprintf(stream, format, arglist);
520 va_end(arglist);
521 return ret;
7ee2227d
SP
522}
523
524int
525Perl_printf_nocontext(const char *format, ...)
526{
527 dTHX;
fc917fff 528 va_list arglist;
3ed3a8af 529 int ret = 0;
7918f24d
NC
530
531#ifdef PERL_IMPLICIT_CONTEXT
532 PERL_ARGS_ASSERT_PRINTF_NOCONTEXT;
533#endif
534
7ee2227d 535 va_start(arglist, format);
3ed3a8af
JH
536 ret = PerlIO_vprintf(PerlIO_stdout(), format, arglist);
537 va_end(arglist);
538 return ret;
7ee2227d
SP
539}
540
541#if defined(HUGE_VAL) || (defined(USE_LONG_DOUBLE) && defined(HUGE_VALL))
542/*
543 * This hack is to force load of "huge" support from libm.a
544 * So it is in perl for (say) POSIX to use.
545 * Needed for SunOS with Sun's 'acc' for example.
546 */
547NV
548Perl_huge(void)
549{
c773ee7a 550# if defined(USE_LONG_DOUBLE) && defined(HUGE_VALL)
7ee2227d 551 return HUGE_VALL;
c773ee7a 552# else
7ee2227d 553 return HUGE_VAL;
c773ee7a 554# endif
7ee2227d
SP
555}
556#endif
557
f2f0f092
NC
558/* compatibility with versions <= 5.003. */
559void
560Perl_gv_fullname(pTHX_ SV *sv, const GV *gv)
561{
7918f24d
NC
562 PERL_ARGS_ASSERT_GV_FULLNAME;
563
666ea192 564 gv_fullname3(sv, gv, sv == (const SV*)gv ? "*" : "");
f2f0f092
NC
565}
566
567/* compatibility with versions <= 5.003. */
568void
569Perl_gv_efullname(pTHX_ SV *sv, const GV *gv)
570{
7918f24d
NC
571 PERL_ARGS_ASSERT_GV_EFULLNAME;
572
666ea192 573 gv_efullname3(sv, gv, sv == (const SV*)gv ? "*" : "");
f2f0f092
NC
574}
575
2674aeec
NC
576void
577Perl_gv_fullname3(pTHX_ SV *sv, const GV *gv, const char *prefix)
578{
7918f24d
NC
579 PERL_ARGS_ASSERT_GV_FULLNAME3;
580
2674aeec
NC
581 gv_fullname4(sv, gv, prefix, TRUE);
582}
583
584void
585Perl_gv_efullname3(pTHX_ SV *sv, const GV *gv, const char *prefix)
586{
7918f24d
NC
587 PERL_ARGS_ASSERT_GV_EFULLNAME3;
588
2674aeec
NC
589 gv_efullname4(sv, gv, prefix, TRUE);
590}
591
887986eb 592/*
3f620621 593=for apidoc_section $GV
887986eb
NC
594=for apidoc gv_fetchmethod
595
ca8b95d7 596See L</gv_fetchmethod_autoload>.
887986eb
NC
597
598=cut
599*/
600
601GV *
602Perl_gv_fetchmethod(pTHX_ HV *stash, const char *name)
603{
7918f24d
NC
604 PERL_ARGS_ASSERT_GV_FETCHMETHOD;
605
887986eb
NC
606 return gv_fetchmethod_autoload(stash, name, TRUE);
607}
608
7a7b9979
NC
609HE *
610Perl_hv_iternext(pTHX_ HV *hv)
611{
7918f24d
NC
612 PERL_ARGS_ASSERT_HV_ITERNEXT;
613
7a7b9979
NC
614 return hv_iternext_flags(hv, 0);
615}
616
bc5cdc23
NC
617void
618Perl_hv_magic(pTHX_ HV *hv, GV *gv, int how)
619{
7918f24d
NC
620 PERL_ARGS_ASSERT_HV_MAGIC;
621
ad64d0ec 622 sv_magic(MUTABLE_SV(hv), MUTABLE_SV(gv), how, NULL, 0);
bc5cdc23
NC
623}
624
34d367cd 625bool
5aaab254 626Perl_do_open(pTHX_ GV *gv, const char *name, I32 len, int as_raw,
e4dba786
NC
627 int rawmode, int rawperm, PerlIO *supplied_fp)
628{
7918f24d
NC
629 PERL_ARGS_ASSERT_DO_OPEN;
630
e4dba786
NC
631 return do_openn(gv, name, len, as_raw, rawmode, rawperm,
632 supplied_fp, (SV **) NULL, 0);
633}
634
635bool
5aaab254 636Perl_do_open9(pTHX_ GV *gv, const char *name, I32 len, int
34d367cd
SP
637as_raw,
638 int rawmode, int rawperm, PerlIO *supplied_fp, SV *svs,
639 I32 num_svs)
640{
7918f24d
NC
641 PERL_ARGS_ASSERT_DO_OPEN9;
642
34d367cd
SP
643 PERL_UNUSED_ARG(num_svs);
644 return do_openn(gv, name, len, as_raw, rawmode, rawperm,
645 supplied_fp, &svs, 1);
646}
647
648int
649Perl_do_binmode(pTHX_ PerlIO *fp, int iotype, int mode)
650{
651 /* The old body of this is now in non-LAYER part of perlio.c
652 * This is a stub for any XS code which might have been calling it.
653 */
654 const char *name = ":raw";
7918f24d
NC
655
656 PERL_ARGS_ASSERT_DO_BINMODE;
657
34d367cd
SP
658#ifdef PERLIO_USING_CRLF
659 if (!(mode & O_BINARY))
660 name = ":crlf";
661#endif
662 return PerlIO_binmode(aTHX_ fp, iotype, mode, name);
663}
664
a9f96b3f
NC
665#ifndef OS2
666bool
5aaab254 667Perl_do_aexec(pTHX_ SV *really, SV **mark, SV **sp)
a9f96b3f 668{
7918f24d
NC
669 PERL_ARGS_ASSERT_DO_AEXEC;
670
a9f96b3f
NC
671 return do_aexec5(really, mark, sp, 0, 0);
672}
673#endif
674
89552e80
NC
675/* Backwards compatibility. */
676int
677Perl_init_i18nl14n(pTHX_ int printwarn)
678{
679 return init_i18nl10n(printwarn);
680}
681
814fafa7 682bool
c41b2540 683Perl_is_utf8_string_loc(const U8 *s, const STRLEN len, const U8 **ep)
814fafa7 684{
7918f24d
NC
685 PERL_ARGS_ASSERT_IS_UTF8_STRING_LOC;
686
814fafa7
NC
687 return is_utf8_string_loclen(s, len, ep, 0);
688}
689
7ee2227d 690/*
3f620621 691=for apidoc_section $SV
d5b2b27b
NC
692=for apidoc sv_nolocking
693
694Dummy routine which "locks" an SV when there is no locking module present.
796b6530 695Exists to avoid test for a C<NULL> function pointer and because it could
d5b2b27b
NC
696potentially warn under some level of strict-ness.
697
796b6530 698"Superseded" by C<sv_nosharing()>.
d5b2b27b
NC
699
700=cut
701*/
702
703void
704Perl_sv_nolocking(pTHX_ SV *sv)
705{
96a5add6 706 PERL_UNUSED_CONTEXT;
d5b2b27b
NC
707 PERL_UNUSED_ARG(sv);
708}
709
710
711/*
712=for apidoc sv_nounlocking
713
714Dummy routine which "unlocks" an SV when there is no locking module present.
796b6530 715Exists to avoid test for a C<NULL> function pointer and because it could
d5b2b27b
NC
716potentially warn under some level of strict-ness.
717
796b6530 718"Superseded" by C<sv_nosharing()>.
d5b2b27b
NC
719
720=cut
af50ae69
KW
721
722PERL_UNLOCK_HOOK in intrpvar.h is the macro that refers to this, and guarantees
723that mathoms gets loaded.
724
d5b2b27b
NC
725*/
726
727void
728Perl_sv_nounlocking(pTHX_ SV *sv)
729{
96a5add6 730 PERL_UNUSED_CONTEXT;
d5b2b27b
NC
731 PERL_UNUSED_ARG(sv);
732}
733
2053acbf
NC
734void
735Perl_save_long(pTHX_ long int *longp)
736{
7918f24d
NC
737 PERL_ARGS_ASSERT_SAVE_LONG;
738
2053acbf
NC
739 SSCHECK(3);
740 SSPUSHLONG(*longp);
741 SSPUSHPTR(longp);
c6bf6a65 742 SSPUSHUV(SAVEt_LONG);
2053acbf
NC
743}
744
745void
2053acbf
NC
746Perl_save_nogv(pTHX_ GV *gv)
747{
7918f24d
NC
748 PERL_ARGS_ASSERT_SAVE_NOGV;
749
2053acbf
NC
750 SSCHECK(2);
751 SSPUSHPTR(gv);
c6bf6a65 752 SSPUSHUV(SAVEt_NSTAB);
2053acbf
NC
753}
754
755void
5aaab254 756Perl_save_list(pTHX_ SV **sarg, I32 maxsarg)
2053acbf 757{
eb578fdb 758 I32 i;
2053acbf 759
7918f24d
NC
760 PERL_ARGS_ASSERT_SAVE_LIST;
761
2053acbf 762 for (i = 1; i <= maxsarg; i++) {
3ed356df
FC
763 SV *sv;
764 SvGETMAGIC(sarg[i]);
765 sv = newSV(0);
766 sv_setsv_nomg(sv,sarg[i]);
2053acbf
NC
767 SSCHECK(3);
768 SSPUSHPTR(sarg[i]); /* remember the pointer */
769 SSPUSHPTR(sv); /* remember the value */
c6bf6a65 770 SSPUSHUV(SAVEt_ITEM);
2053acbf
NC
771 }
772}
773
47518d95
NC
774/*
775=for apidoc sv_usepvn_mg
776
777Like C<sv_usepvn>, but also handles 'set' magic.
778
779=cut
780*/
781
782void
783Perl_sv_usepvn_mg(pTHX_ SV *sv, char *ptr, STRLEN len)
784{
7918f24d
NC
785 PERL_ARGS_ASSERT_SV_USEPVN_MG;
786
47518d95
NC
787 sv_usepvn_flags(sv,ptr,len, SV_SMAGIC);
788}
789
790/*
791=for apidoc sv_usepvn
792
72d33970 793Tells an SV to use C<ptr> to find its string value. Implemented by
47518d95 794calling C<sv_usepvn_flags> with C<flags> of 0, hence does not handle 'set'
fbe13c60 795magic. See C<L</sv_usepvn_flags>>.
47518d95
NC
796
797=cut
798*/
799
800void
801Perl_sv_usepvn(pTHX_ SV *sv, char *ptr, STRLEN len)
802{
7918f24d
NC
803 PERL_ARGS_ASSERT_SV_USEPVN;
804
47518d95
NC
805 sv_usepvn_flags(sv,ptr,len, 0);
806}
807
c03e83bf 808/*
3f620621 809=for apidoc_section $pack
c03e83bf
NC
810=for apidoc unpack_str
811
796b6530
KW
812The engine implementing C<unpack()> Perl function. Note: parameters C<strbeg>,
813C<new_s> and C<ocnt> are not used. This call should not be used, use
814C<unpackstring> instead.
c03e83bf
NC
815
816=cut */
817
e1b825c1 818SSize_t
c03e83bf
NC
819Perl_unpack_str(pTHX_ const char *pat, const char *patend, const char *s,
820 const char *strbeg, const char *strend, char **new_s, I32 ocnt,
821 U32 flags)
822{
7918f24d
NC
823 PERL_ARGS_ASSERT_UNPACK_STR;
824
c03e83bf
NC
825 PERL_UNUSED_ARG(strbeg);
826 PERL_UNUSED_ARG(new_s);
827 PERL_UNUSED_ARG(ocnt);
828
829 return unpackstring(pat, patend, s, strend, flags);
830}
b47163a2
NC
831
832/*
833=for apidoc pack_cat
834
796b6530
KW
835The engine implementing C<pack()> Perl function. Note: parameters
836C<next_in_list> and C<flags> are not used. This call should not be used; use
550697d6 837C<L</packlist>> instead.
b47163a2
NC
838
839=cut
840*/
841
842void
5aaab254 843Perl_pack_cat(pTHX_ SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags)
b47163a2 844{
7918f24d
NC
845 PERL_ARGS_ASSERT_PACK_CAT;
846
b47163a2
NC
847 PERL_UNUSED_ARG(next_in_list);
848 PERL_UNUSED_ARG(flags);
849
850 packlist(cat, pat, patend, beglist, endlist);
851}
4c2df08c
NC
852
853HE *
854Perl_hv_store_ent(pTHX_ HV *hv, SV *keysv, SV *val, U32 hash)
855{
59af68cc 856 return (HE *)hv_common(hv, keysv, NULL, 0, 0, HV_FETCH_ISSTORE, val, hash);
4c2df08c
NC
857}
858
859bool
860Perl_hv_exists_ent(pTHX_ HV *hv, SV *keysv, U32 hash)
861{
7918f24d
NC
862 PERL_ARGS_ASSERT_HV_EXISTS_ENT;
863
8298454c 864 return cBOOL(hv_common(hv, keysv, NULL, 0, 0, HV_FETCH_ISEXISTS, 0, hash));
4c2df08c
NC
865}
866
867HE *
868Perl_hv_fetch_ent(pTHX_ HV *hv, SV *keysv, I32 lval, U32 hash)
869{
7918f24d
NC
870 PERL_ARGS_ASSERT_HV_FETCH_ENT;
871
59af68cc 872 return (HE *)hv_common(hv, keysv, NULL, 0, 0,
4c2df08c
NC
873 (lval ? HV_FETCH_LVALUE : 0), NULL, hash);
874}
875
876SV *
877Perl_hv_delete_ent(pTHX_ HV *hv, SV *keysv, I32 flags, U32 hash)
878{
7918f24d
NC
879 PERL_ARGS_ASSERT_HV_DELETE_ENT;
880
ad64d0ec
NC
881 return MUTABLE_SV(hv_common(hv, keysv, NULL, 0, 0, flags | HV_DELETE, NULL,
882 hash));
4c2df08c
NC
883}
884
a038e571
NC
885SV**
886Perl_hv_store_flags(pTHX_ HV *hv, const char *key, I32 klen, SV *val, U32 hash,
887 int flags)
888{
889 return (SV**) hv_common(hv, NULL, key, klen, flags,
890 (HV_FETCH_ISSTORE|HV_FETCH_JUST_SV), val, hash);
891}
892
893SV**
894Perl_hv_store(pTHX_ HV *hv, const char *key, I32 klen_i32, SV *val, U32 hash)
895{
896 STRLEN klen;
897 int flags;
898
899 if (klen_i32 < 0) {
900 klen = -klen_i32;
901 flags = HVhek_UTF8;
902 } else {
903 klen = klen_i32;
904 flags = 0;
905 }
906 return (SV **) hv_common(hv, NULL, key, klen, flags,
907 (HV_FETCH_ISSTORE|HV_FETCH_JUST_SV), val, hash);
908}
909
910bool
911Perl_hv_exists(pTHX_ HV *hv, const char *key, I32 klen_i32)
912{
913 STRLEN klen;
914 int flags;
915
7918f24d
NC
916 PERL_ARGS_ASSERT_HV_EXISTS;
917
a038e571
NC
918 if (klen_i32 < 0) {
919 klen = -klen_i32;
920 flags = HVhek_UTF8;
921 } else {
922 klen = klen_i32;
923 flags = 0;
924 }
8298454c 925 return cBOOL(hv_common(hv, NULL, key, klen, flags, HV_FETCH_ISEXISTS, 0, 0));
a038e571
NC
926}
927
928SV**
929Perl_hv_fetch(pTHX_ HV *hv, const char *key, I32 klen_i32, I32 lval)
930{
931 STRLEN klen;
932 int flags;
933
7918f24d
NC
934 PERL_ARGS_ASSERT_HV_FETCH;
935
a038e571
NC
936 if (klen_i32 < 0) {
937 klen = -klen_i32;
938 flags = HVhek_UTF8;
939 } else {
940 klen = klen_i32;
941 flags = 0;
942 }
943 return (SV **) hv_common(hv, NULL, key, klen, flags,
944 lval ? (HV_FETCH_JUST_SV | HV_FETCH_LVALUE)
945 : HV_FETCH_JUST_SV, NULL, 0);
946}
947
948SV *
949Perl_hv_delete(pTHX_ HV *hv, const char *key, I32 klen_i32, I32 flags)
950{
951 STRLEN klen;
952 int k_flags;
953
7918f24d
NC
954 PERL_ARGS_ASSERT_HV_DELETE;
955
a038e571
NC
956 if (klen_i32 < 0) {
957 klen = -klen_i32;
958 k_flags = HVhek_UTF8;
959 } else {
960 klen = klen_i32;
961 k_flags = 0;
962 }
ad64d0ec
NC
963 return MUTABLE_SV(hv_common(hv, NULL, key, klen, k_flags, flags | HV_DELETE,
964 NULL, 0));
a038e571
NC
965}
966
ac572bf4
NC
967AV *
968Perl_newAV(pTHX)
969{
502c6561 970 return MUTABLE_AV(newSV_type(SVt_PVAV));
ac572bf4
NC
971 /* sv_upgrade does AvREAL_only():
972 AvALLOC(av) = 0;
973 AvARRAY(av) = NULL;
974 AvMAX(av) = AvFILLp(av) = -1; */
975}
976
78ac7dd9
NC
977HV *
978Perl_newHV(pTHX)
979{
85fbaab2 980 HV * const hv = MUTABLE_HV(newSV_type(SVt_PVHV));
78ac7dd9
NC
981 assert(!SvOK(hv));
982
983 return hv;
984}
985
84335ee9
NC
986void
987Perl_sv_insert(pTHX_ SV *const bigstr, const STRLEN offset, const STRLEN len,
988 const char *const little, const STRLEN littlelen)
989{
990 PERL_ARGS_ASSERT_SV_INSERT;
991 sv_insert_flags(bigstr, offset, len, little, littlelen, SV_GMAGIC);
992}
993
2fd8beea
NC
994void
995Perl_save_freesv(pTHX_ SV *sv)
996{
2fd8beea
NC
997 save_freesv(sv);
998}
999
1000void
1001Perl_save_mortalizesv(pTHX_ SV *sv)
1002{
2fd8beea
NC
1003 PERL_ARGS_ASSERT_SAVE_MORTALIZESV;
1004
1005 save_mortalizesv(sv);
1006}
1007
1008void
1009Perl_save_freeop(pTHX_ OP *o)
1010{
2fd8beea
NC
1011 save_freeop(o);
1012}
1013
1014void
1015Perl_save_freepv(pTHX_ char *pv)
1016{
2fd8beea
NC
1017 save_freepv(pv);
1018}
1019
1020void
1021Perl_save_op(pTHX)
1022{
2fd8beea
NC
1023 save_op();
1024}
1025
d5713896
NC
1026#ifdef PERL_DONT_CREATE_GVSV
1027GV *
1028Perl_gv_SVadd(pTHX_ GV *gv)
1029{
d5713896
NC
1030 return gv_SVadd(gv);
1031}
1032#endif
1033
1034GV *
1035Perl_gv_AVadd(pTHX_ GV *gv)
1036{
d5713896
NC
1037 return gv_AVadd(gv);
1038}
1039
1040GV *
5aaab254 1041Perl_gv_HVadd(pTHX_ GV *gv)
d5713896 1042{
d5713896
NC
1043 return gv_HVadd(gv);
1044}
1045
bb85b28a 1046GV *
5aaab254 1047Perl_gv_IOadd(pTHX_ GV *gv)
bb85b28a
NC
1048{
1049 return gv_IOadd(gv);
1050}
1051
85dca89a
NC
1052IO *
1053Perl_newIO(pTHX)
1054{
1055 return MUTABLE_IO(newSV_type(SVt_PVIO));
1056}
1057
0d7d409d
DM
1058I32
1059Perl_my_stat(pTHX)
1060{
1061 return my_stat_flags(SV_GMAGIC);
1062}
1063
1064I32
1065Perl_my_lstat(pTHX)
1066{
1067 return my_lstat_flags(SV_GMAGIC);
1068}
1069
078504b2 1070I32
5aaab254 1071Perl_sv_eq(pTHX_ SV *sv1, SV *sv2)
078504b2
FC
1072{
1073 return sv_eq_flags(sv1, sv2, SV_GMAGIC);
1074}
1075
6129b56c 1076#ifdef USE_LOCALE_COLLATE
078504b2
FC
1077char *
1078Perl_sv_collxfrm(pTHX_ SV *const sv, STRLEN *const nxp)
1079{
1545ba5b 1080 PERL_ARGS_ASSERT_SV_COLLXFRM;
078504b2
FC
1081 return sv_collxfrm_flags(sv, nxp, SV_GMAGIC);
1082}
78d57975
KW
1083
1084char *
1085Perl_mem_collxfrm(pTHX_ const char *input_string, STRLEN len, STRLEN *xlen)
1086{
1087 /* This function is retained for compatibility in case someone outside core
1088 * is using this (but it is undocumented) */
1089
1090 PERL_ARGS_ASSERT_MEM_COLLXFRM;
1091
1092 return _mem_collxfrm(input_string, len, xlen, FALSE);
1093}
1094
6129b56c 1095#endif
078504b2 1096
06c841cf 1097bool
5aaab254 1098Perl_sv_2bool(pTHX_ SV *const sv)
06c841cf 1099{
1545ba5b 1100 PERL_ARGS_ASSERT_SV_2BOOL;
06c841cf
FC
1101 return sv_2bool_flags(sv, SV_GMAGIC);
1102}
1103
1830b3d9 1104
9733086d 1105/*
3f620621 1106=for apidoc_section $custom
9733086d 1107=for apidoc custom_op_name
796b6530 1108Return the name for a given custom op. This was once used by the C<OP_NAME>
9733086d
BM
1109macro, but is no longer: it has only been kept for compatibility, and
1110should not be used.
1111
1112=for apidoc custom_op_desc
72d33970 1113Return the description of a given custom op. This was once used by the
796b6530 1114C<OP_DESC> macro, but is no longer: it has only been kept for
9733086d
BM
1115compatibility, and should not be used.
1116
1117=cut
1118*/
1119
1830b3d9
BM
1120const char*
1121Perl_custom_op_name(pTHX_ const OP* o)
1122{
1123 PERL_ARGS_ASSERT_CUSTOM_OP_NAME;
ae103e09 1124 return XopENTRYCUSTOM(o, xop_name);
1830b3d9
BM
1125}
1126
1127const char*
1128Perl_custom_op_desc(pTHX_ const OP* o)
1129{
1130 PERL_ARGS_ASSERT_CUSTOM_OP_DESC;
ae103e09 1131 return XopENTRYCUSTOM(o, xop_desc);
1830b3d9 1132}
7bff8c33
NC
1133
1134CV *
1135Perl_newSUB(pTHX_ I32 floor, OP *o, OP *proto, OP *block)
1136{
e8f91c91 1137 return newATTRSUB(floor, o, proto, NULL, block);
7bff8c33 1138}
0c9b0438 1139
108cb980 1140SV *
37ee558d 1141Perl_sv_mortalcopy(pTHX_ SV *const oldsv)
108cb980 1142{
37ee558d 1143 return Perl_sv_mortalcopy_flags(aTHX_ oldsv, SV_GMAGIC);
108cb980
FC
1144}
1145
e4524c4c
DD
1146void
1147Perl_sv_copypv(pTHX_ SV *const dsv, SV *const ssv)
1148{
1149 PERL_ARGS_ASSERT_SV_COPYPV;
1150
6338d1c6 1151 sv_copypv_flags(dsv, ssv, SV_GMAGIC);
e4524c4c
DD
1152}
1153
3d81eea6
KW
1154UV /* Made into a function, so can be deprecated */
1155NATIVE_TO_NEED(const UV enc, const UV ch)
1156{
1157 PERL_UNUSED_ARG(enc);
1158 return ch;
1159}
1160
1161UV /* Made into a function, so can be deprecated */
1162ASCII_TO_NEED(const UV enc, const UV ch)
1163{
1164 PERL_UNUSED_ARG(enc);
1165 return ch;
1166}
1167
f2645549 1168/*
3f620621 1169=for apidoc_section $unicode
f2645549
KW
1170=for apidoc is_utf8_char
1171
1172Tests if some arbitrary number of bytes begins in a valid UTF-8
1173character. Note that an INVARIANT (i.e. ASCII on non-EBCDIC machines)
1174character is a valid UTF-8 character. The actual number of bytes in the UTF-8
1175character will be returned if it is valid, otherwise 0.
1176
1177This function is deprecated due to the possibility that malformed input could
1178cause reading beyond the end of the input buffer. Use L</isUTF8_CHAR>
1179instead.
1180
1181=cut */
1182
1183STRLEN
1184Perl_is_utf8_char(const U8 *s)
1185{
1186 PERL_ARGS_ASSERT_IS_UTF8_CHAR;
1187
c6734c35 1188 /* Assumes we have enough space, which is why this is deprecated. But the
00e53078
KW
1189 * UTF8_CHK_SKIP(s)) makes it safe for the common case of NUL-terminated
1190 * strings */
1191 return isUTF8_CHAR(s, s + UTF8_CHK_SKIP(s));
f2645549
KW
1192}
1193
e4524c4c
DD
1194/*
1195=for apidoc is_utf8_char_buf
1196
09232555 1197This is identical to the macro L<perlapi/isUTF8_CHAR>.
e4524c4c
DD
1198
1199=cut */
1200
1201STRLEN
1202Perl_is_utf8_char_buf(const U8 *buf, const U8* buf_end)
1203{
1204
1205 PERL_ARGS_ASSERT_IS_UTF8_CHAR_BUF;
1206
1207 return isUTF8_CHAR(buf, buf_end);
1208}
1209
f2645549
KW
1210/* DEPRECATED!
1211 * Like L</utf8_to_uvuni_buf>(), but should only be called when it is known that
1212 * there are no malformations in the input UTF-8 string C<s>. Surrogates,
1213 * non-character code points, and non-Unicode code points are allowed */
1214
1215UV
1216Perl_valid_utf8_to_uvuni(pTHX_ const U8 *s, STRLEN *retlen)
1217{
e9b8343f 1218 PERL_UNUSED_CONTEXT;
f2645549
KW
1219 PERL_ARGS_ASSERT_VALID_UTF8_TO_UVUNI;
1220
1221 return NATIVE_TO_UNI(valid_utf8_to_uvchr(s, retlen));
1222}
1223
1224/*
f2645549
KW
1225=for apidoc utf8_to_uvuni
1226
1227Returns the Unicode code point of the first character in the string C<s>
1228which is assumed to be in UTF-8 encoding; C<retlen> will be set to the
1229length, in bytes, of that character.
1230
1231Some, but not all, UTF-8 malformations are detected, and in fact, some
1232malformed input could cause reading beyond the end of the input buffer, which
1233is one reason why this function is deprecated. The other is that only in
1234extremely limited circumstances should the Unicode versus native code point be
1235of any interest to you. See L</utf8_to_uvuni_buf> for alternatives.
1236
1237If C<s> points to one of the detected malformations, and UTF8 warnings are
1238enabled, zero is returned and C<*retlen> is set (if C<retlen> doesn't point to
1239NULL) to -1. If those warnings are off, the computed value if well-defined (or
1240the Unicode REPLACEMENT CHARACTER, if not) is silently returned, and C<*retlen>
1241is set (if C<retlen> isn't NULL) so that (S<C<s> + C<*retlen>>) is the
1242next possible position in C<s> that could begin a non-malformed character.
09232555 1243See L<perlapi/utf8n_to_uvchr> for details on when the REPLACEMENT CHARACTER is returned.
f2645549
KW
1244
1245=cut
1246*/
1247
1248UV
1249Perl_utf8_to_uvuni(pTHX_ const U8 *s, STRLEN *retlen)
1250{
e9b8343f 1251 PERL_UNUSED_CONTEXT;
f2645549
KW
1252 PERL_ARGS_ASSERT_UTF8_TO_UVUNI;
1253
1254 return NATIVE_TO_UNI(valid_utf8_to_uvchr(s, retlen));
1255}
1256
09d7a3ba 1257/*
44170c9a 1258=for apidoc pad_compname_type
09d7a3ba 1259
2d7f6611 1260Looks up the type of the lexical variable at position C<po> in the
09d7a3ba
FC
1261currently-compiling pad. If the variable is typed, the stash of the
1262class to which it is typed is returned. If not, C<NULL> is returned.
1263
5c27e8a2
KW
1264Use L<perlintern/C<PAD_COMPNAME_TYPE>> instead.
1265
09d7a3ba
FC
1266=cut
1267*/
1268
1269HV *
1270Perl_pad_compname_type(pTHX_ const PADOFFSET po)
1271{
1272 return PAD_COMPNAME_TYPE(po);
1273}
1274
534dad48 1275/* return ptr to little string in big string, NULL if not found */
fb245905 1276/* The original version of this routine was donated by Corey Satten. */
534dad48
CB
1277
1278char *
1279Perl_instr(const char *big, const char *little)
1280{
534dad48 1281 PERL_ARGS_ASSERT_INSTR;
534dad48 1282
4e528812 1283 return instr(big, little);
534dad48 1284}
0ddd4a5b 1285
238f2c13
P
1286SV *
1287Perl_newSVsv(pTHX_ SV *const old)
1288{
1289 return newSVsv(old);
1290}
1291
423ce623
P
1292bool
1293Perl_sv_utf8_downgrade(pTHX_ SV *const sv, const bool fail_ok)
1294{
1295 PERL_ARGS_ASSERT_SV_UTF8_DOWNGRADE;
1296
1297 return sv_utf8_downgrade(sv, fail_ok);
1298}
1299
757fc329
P
1300char *
1301Perl_sv_2pvutf8(pTHX_ SV *sv, STRLEN *const lp)
1302{
1303 PERL_ARGS_ASSERT_SV_2PVUTF8;
1304
1305 return sv_2pvutf8(sv, lp);
1306}
1307
1308char *
1309Perl_sv_2pvbyte(pTHX_ SV *sv, STRLEN *const lp)
1310{
1311 PERL_ARGS_ASSERT_SV_2PVBYTE;
1312
1313 return sv_2pvbyte(sv, lp);
1314}
1315
86a5062a
KW
1316U8 *
1317Perl_uvuni_to_utf8(pTHX_ U8 *d, UV uv)
1318{
1319 PERL_ARGS_ASSERT_UVUNI_TO_UTF8;
1320
1321 return uvoffuni_to_utf8_flags(d, uv, 0);
1322}
1323
1324/*
1325=for apidoc utf8n_to_uvuni
1326
1327Instead use L<perlapi/utf8_to_uvchr_buf>, or rarely, L<perlapi/utf8n_to_uvchr>.
1328
1329This function was useful for code that wanted to handle both EBCDIC and
1330ASCII platforms with Unicode properties, but starting in Perl v5.20, the
1331distinctions between the platforms have mostly been made invisible to most
1332code, so this function is quite unlikely to be what you want. If you do need
1333this precise functionality, use instead
1334C<L<NATIVE_TO_UNI(utf8_to_uvchr_buf(...))|perlapi/utf8_to_uvchr_buf>>
1335or C<L<NATIVE_TO_UNI(utf8n_to_uvchr(...))|perlapi/utf8n_to_uvchr>>.
1336
1337=cut
1338*/
1339
1340UV
1341Perl_utf8n_to_uvuni(pTHX_ const U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags)
1342{
1343 PERL_ARGS_ASSERT_UTF8N_TO_UVUNI;
1344
1345 return NATIVE_TO_UNI(utf8n_to_uvchr(s, curlen, retlen, flags));
1346}
1347
1348/*
1349=for apidoc uvuni_to_utf8_flags
1350
1351Instead you almost certainly want to use L<perlapi/uvchr_to_utf8> or
1352L<perlapi/uvchr_to_utf8_flags>.
1353
1354This function is a deprecated synonym for L</uvoffuni_to_utf8_flags>,
1355which itself, while not deprecated, should be used only in isolated
1356circumstances. These functions were useful for code that wanted to handle
1357both EBCDIC and ASCII platforms with Unicode properties, but starting in Perl
1358v5.20, the distinctions between the platforms have mostly been made invisible
1359to most code, so this function is quite unlikely to be what you want.
1360
1361=cut
1362*/
1363
1364U8 *
1365Perl_uvuni_to_utf8_flags(pTHX_ U8 *d, UV uv, UV flags)
1366{
1367 PERL_ARGS_ASSERT_UVUNI_TO_UTF8_FLAGS;
1368
1369 return uvoffuni_to_utf8_flags(d, uv, flags);
1370}
1371
1372/*
1373=for apidoc utf8_to_uvchr
1374
1375Returns the native code point of the first character in the string C<s>
1376which is assumed to be in UTF-8 encoding; C<retlen> will be set to the
1377length, in bytes, of that character.
1378
1379Some, but not all, UTF-8 malformations are detected, and in fact, some
1380malformed input could cause reading beyond the end of the input buffer, which
1381is why this function is deprecated. Use L</utf8_to_uvchr_buf> instead.
1382
1383If C<s> points to one of the detected malformations, and UTF8 warnings are
1384enabled, zero is returned and C<*retlen> is set (if C<retlen> isn't
1385C<NULL>) to -1. If those warnings are off, the computed value if well-defined (or
1386the Unicode REPLACEMENT CHARACTER, if not) is silently returned, and C<*retlen>
1387is set (if C<retlen> isn't NULL) so that (S<C<s> + C<*retlen>>) is the
1388next possible position in C<s> that could begin a non-malformed character.
1389See L</utf8n_to_uvchr> for details on when the REPLACEMENT CHARACTER is returned.
1390
1391=cut
1392*/
1393
1394UV
1395Perl_utf8_to_uvchr(pTHX_ const U8 *s, STRLEN *retlen)
1396{
1397 PERL_ARGS_ASSERT_UTF8_TO_UVCHR;
1398
1399 /* This function is unsafe if malformed UTF-8 input is given it, which is
1400 * why the function is deprecated. If the first byte of the input
1401 * indicates that there are more bytes remaining in the sequence that forms
1402 * the character than there are in the input buffer, it can read past the
1403 * end. But we can make it safe if the input string happens to be
1404 * NUL-terminated, as many strings in Perl are, by refusing to read past a
1405 * NUL, which is what UTF8_CHK_SKIP() does. A NUL indicates the start of
1406 * the next character anyway. If the input isn't NUL-terminated, the
1407 * function remains unsafe, as it always has been. */
1408
1409 return utf8_to_uvchr_buf(s, s + UTF8_CHK_SKIP(s), retlen);
1410}
1411
238965b4
KW
1412GCC_DIAG_RESTORE
1413
20fac488
GA
1414#endif /* NO_MATHOMS */
1415
d5b2b27b 1416/*
14d04a33 1417 * ex: set ts=8 sts=4 sw=4 et:
7ee2227d 1418 */