Debian Codegraph @

upstream/mageia-cauldron/man3pm/builtin.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "builtin 3pm"
61 .TH builtin 3pm 2025-06-24 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 builtin \- Perl pragma to import built\-in utility functions
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 10
71 \& use builtin qw(
72 \& true false is_bool
73 \& inf nan
74 \& weaken unweaken is_weak
75 \& blessed refaddr reftype
76 \& created_as_string created_as_number
77 \& stringify
78 \& ceil floor
79 \& indexed
80 \& trim
81 \& is_tainted
82 \& export_lexically
83 \& load_module
84 \& );
85 \&
86 \& use builtin \*(Aq:5.40\*(Aq; # most of the above
87 .Ve
88 .SH DESCRIPTION
89 .IX Header "DESCRIPTION"
90 Perl provides several utility functions in the \f(CW\*(C`builtin\*(C'\fR package. These are
91 plain functions, and look and behave just like regular user\-defined functions
92 do. They do not provide new syntax or require special parsing. These functions
93 are always present in the interpreter and can be called at any time by their
94 fully\-qualified names. By default they are not available as short names, but
95 can be requested for convenience.
96 .PP
97 Individual named functions can be imported by listing them as import
98 parameters on the \f(CW\*(C`use\*(C'\fR statement for this pragma.
99 .PP
100 The builtin::compat module from CPAN provides versions of many of these
101 functions that can be used on Perl versions where \f(CW\*(C`builtin\*(C'\fR or specific
102 functions are not yet available.
103 .PP
104 \&\fBWarning\fR: At present, many of the functions in the \f(CW\*(C`builtin\*(C'\fR namespace are
105 experimental. Calling them will trigger warnings of the
106 \&\f(CW\*(C`experimental::builtin\*(C'\fR category.
107 .SS "Lexical Import"
108 .IX Subsection "Lexical Import"
109 This pragma module creates \fIlexical\fR aliases in the currently\-compiling scope
110 to these builtin functions. This is similar to the lexical effect of other
111 pragmas such as strict and feature.
112 .PP
113 .Vb 3
114 \& sub classify
115 \& {
116 \& my $val = shift;
117 \&
118 \& use builtin \*(Aqis_bool\*(Aq;
119 \& return is_bool($val) ? "boolean" : "not a boolean";
120 \& }
121 \&
122 \& # the is_bool() function is no longer visible here
123 \& # but may still be called by builtin::is_bool()
124 .Ve
125 .PP
126 Because these functions are imported lexically, rather than by package
127 symbols, the user does not need to take any special measures to ensure they
128 don\*(Aqt accidentally appear as object methods from a class.
129 .PP
130 .Vb 4
131 \& package An::Object::Class {
132 \& use builtin \*(Aqtrue\*(Aq, \*(Aqfalse\*(Aq;
133 \& ...
134 \& }
135 \&
136 \& # does not appear as a method
137 \& An::Object::Class\->true;
138 \&
139 \& # Can\*(Aqt locate object method "true" via package "An::Object::Class"
140 \& # at ...
141 .Ve
142 .PP
143 Once imported, a lexical function is much like any other lexical symbol
144 (such as a variable) in that it cannot be removed again. If you wish to
145 limit the visiblity of an imported \f(CW\*(C`builtin\*(C'\fR function, put it inside its
146 own scope:
147 .PP
148 .Vb 4
149 \& {
150 \& use builtin \*(Aqrefaddr\*(Aq;
151 \& ...
152 \& }
153 .Ve
154 .SS "Version Bundles"
155 .IX Subsection "Version Bundles"
156 The entire set of builtin functions that were considered non\-experimental by a
157 version of perl can be imported all at once, by requesting a version bundle.
158 This is done by giving the perl release version (without its subversion
159 suffix) after a colon character:
160 .PP
161 .Vb 1
162 \& use builtin \*(Aq:5.40\*(Aq;
163 .Ve
164 .PP
165 The following bundles currently exist:
166 .PP
167 .Vb 2
168 \& Version Includes
169 \& \-\-\-\-\-\-\- \-\-\-\-\-\-\-\-
170 \&
171 \& :5.40 true false weaken unweaken is_weak blessed refaddr reftype
172 \& ceil floor is_tainted trim indexed
173 .Ve
174 .SS "Function Optimisations"
175 .IX Subsection "Function Optimisations"
176 There are a number of optimisations that apply to functions in the builtin
177 package. If you replace or override these functions (such as by assignment
178 into glob references) the optimisations may not take effect. Do so with
179 caution.
180 .SH FUNCTIONS
181 .IX Header "FUNCTIONS"
182 .SS true
183 .IX Subsection "true"
184 .Vb 1
185 \& $val = true;
186 .Ve
187 .PP
188 Returns the boolean truth value. While any scalar value can be tested for
189 truth and most defined, non\-empty and non\-zero values are considered "true"
190 by perl, this one is special in that "is_bool" considers it to be a
191 distinguished boolean value.
192 .PP
193 This gives an equivalent value to expressions like \f(CW\*(C`!!1\*(C'\fR or \f(CW\*(C`!0\*(C'\fR.
194 .PP
195 Available starting with Perl 5.36. Since Perl 5.40, it is no longer
196 experimental and it is included in the 5.40 and higher builtin version
197 bundles.
198 .SS false
199 .IX Subsection "false"
200 .Vb 1
201 \& $val = false;
202 .Ve
203 .PP
204 Returns the boolean false value. While any non\-true scalar value is
205 considered "false" by perl, this one is special in that "is_bool" considers
206 it to be a distinguished boolean value.
207 .PP
208 This gives an equivalent value to expressions like \f(CW\*(C`!!0\*(C'\fR or \f(CW\*(C`!1\*(C'\fR.
209 .PP
210 Available starting with Perl 5.36. Since Perl 5.40, it is no longer
211 experimental and it is included in the 5.40 and higher builtin version
212 bundles.
213 .SS is_bool
214 .IX Subsection "is_bool"
215 .Vb 1
216 \& $bool = is_bool($val);
217 .Ve
218 .PP
219 This function is currently \fBexperimental\fR.
220 .PP
221 Returns true when given a distinguished boolean value, or false if not. A
222 distinguished boolean value is the result of any boolean\-returning builtin
223 function (such as \f(CW\*(C`true\*(C'\fR or \f(CW\*(C`is_bool\*(C'\fR itself), boolean\-returning operator
224 (such as the \f(CW\*(C`eq\*(C'\fR or \f(CW\*(C`==\*(C'\fR comparison tests or the \f(CW\*(C`!\*(C'\fR negation operator),
225 or any variable containing one of these results.
226 .PP
227 This function used to be named \f(CW\*(C`isbool\*(C'\fR. A compatibility alias is provided
228 currently but will be removed in a later version.
229 .PP
230 Available starting with Perl 5.36.
231 .SS inf
232 .IX Subsection "inf"
233 .Vb 1
234 \& $num = inf;
235 .Ve
236 .PP
237 This function is currently \fBexperimental\fR.
238 .PP
239 Returns the floating\-point infinity value. If the underlying numeric C type
240 does not support such a value, it throws a runtime error instead.
241 .PP
242 Available starting with Perl 5.40.
243 .SS nan
244 .IX Subsection "nan"
245 .Vb 1
246 \& $num = nan;
247 .Ve
248 .PP
249 This function is currently \fBexperimental\fR.
250 .PP
251 Returns the floating\-point "Not\-a\-Number" value. If the underlying numeric C
252 type does not support such a value, it throws a runtime error instead.
253 .PP
254 Available starting with Perl 5.40.
255 .SS weaken
256 .IX Subsection "weaken"
257 .Vb 1
258 \& weaken($ref);
259 .Ve
260 .PP
261 Weakens a reference. A weakened reference does not contribute to the reference
262 count of its referent. If only weakened references to a referent remain, it
263 will be disposed of, and all remaining weak references to it will have their
264 value set to \f(CW\*(C`undef\*(C'\fR.
265 .PP
266 Available starting with Perl 5.36. Since Perl 5.40, it is no longer
267 experimental and it is included in the 5.40 and higher builtin version
268 bundles.
269 .SS unweaken
270 .IX Subsection "unweaken"
271 .Vb 1
272 \& unweaken($ref);
273 .Ve
274 .PP
275 Strengthens a reference, undoing the effects of a previous call to "weaken".
276 .PP
277 Available starting with Perl 5.36. Since Perl 5.40, it is no longer
278 experimental and it is included in the 5.40 and higher builtin version
279 bundles.
280 .SS is_weak
281 .IX Subsection "is_weak"
282 .Vb 1
283 \& $bool = is_weak($ref);
284 .Ve
285 .PP
286 Returns true when given a weakened reference, or false if not a reference or
287 not weak.
288 .PP
289 This function used to be named \f(CW\*(C`isweak\*(C'\fR. A compatibility alias is provided
290 currently but will be removed in a later version.
291 .PP
292 Available starting with Perl 5.36. Since Perl 5.40, it is no longer
293 experimental and it is included in the 5.40 and higher builtin version
294 bundles.
295 .SS blessed
296 .IX Subsection "blessed"
297 .Vb 1
298 \& $str = blessed($ref);
299 .Ve
300 .PP
301 Returns the package name for an object reference, or \f(CW\*(C`undef\*(C'\fR for a
302 non\-reference or reference that is not an object.
303 .PP
304 Available starting with Perl 5.36. Since Perl 5.40, it is no longer
305 experimental and it is included in the 5.40 and higher builtin version
306 bundles.
307 .SS refaddr
308 .IX Subsection "refaddr"
309 .Vb 1
310 \& $num = refaddr($ref);
311 .Ve
312 .PP
313 Returns the memory address for a reference, or \f(CW\*(C`undef\*(C'\fR for a non\-reference.
314 This value is not likely to be very useful for pure Perl code, but is handy as
315 a means to test for referential identity or uniqueness.
316 .PP
317 Available starting with Perl 5.36. Since Perl 5.40, it is no longer
318 experimental and it is included in the 5.40 and higher builtin version
319 bundles.
320 .SS reftype
321 .IX Subsection "reftype"
322 .Vb 1
323 \& $str = reftype($ref);
324 .Ve
325 .PP
326 Returns the basic container type of the referent of a reference, or \f(CW\*(C`undef\*(C'\fR
327 for a non\-reference. This is returned as a string in all\-capitals, such as
328 \&\f(CW\*(C`ARRAY\*(C'\fR for array references, or \f(CW\*(C`HASH\*(C'\fR for hash references.
329 .PP
330 Available starting with Perl 5.36. Since Perl 5.40, it is no longer
331 experimental and it is included in the 5.40 and higher builtin version
332 bundles.
333 .SS created_as_string
334 .IX Subsection "created_as_string"
335 .Vb 1
336 \& $bool = created_as_string($val);
337 .Ve
338 .PP
339 This function is currently \fBexperimental\fR.
340 .PP
341 Returns a boolean representing if the argument value was originally created as
342 a string. It will return true for any scalar expression whose most recent
343 assignment or modification was of a string\-like nature \- such as assignment
344 from a string literal, or the result of a string operation such as
345 concatenation or regexp. It will return false for references (including any
346 object), numbers, booleans and undef.
347 .PP
348 It is unlikely that you will want to use this for regular data validation
349 within Perl, as it will not return true for regular numbers that are still
350 perfectly usable as strings, nor for any object reference \- especially objects
351 that overload the stringification operator in an attempt to behave more like
352 strings. For example
353 .PP
354 .Vb 1
355 \& my $val = URI\->new( "https://metacpan.org/" );
356 \&
357 \& if( created_as_string $val ) { ... } # this will not execute
358 .Ve
359 .PP
360 Available starting with Perl 5.36.
361 .SS created_as_number
362 .IX Subsection "created_as_number"
363 .Vb 1
364 \& $bool = created_as_number($val);
365 .Ve
366 .PP
367 This function is currently \fBexperimental\fR.
368 .PP
369 Returns a boolean representing if the argument value was originally created as
370 a number. It will return true for any scalar expression whose most recent
371 assignment or modification was of a numerical nature \- such as assignment from
372 a number literal, or the result of a numerical operation such as addition. It
373 will return false for references (including any object), strings, booleans and
374 undef.
375 .PP
376 It is unlikely that you will want to use this for regular data validation
377 within Perl, as it will not return true for regular strings of decimal digits
378 that are still perfectly usable as numbers, nor for any object reference \-
379 especially objects that overload the numification operator in an attempt to
380 behave more like numbers. For example
381 .PP
382 .Vb 1
383 \& my $val = Math::BigInt\->new( 123 );
384 \&
385 \& if( created_as_number $val ) { ... } # this will not execute
386 .Ve
387 .PP
388 While most Perl code should operate on scalar values without needing to know
389 their creation history, these two functions are intended to be used by data
390 serialisation modules such as JSON encoders or similar situations, where
391 language interoperability concerns require making a distinction between values
392 that are fundamentally stringlike versus numberlike in nature.
393 .PP
394 Available starting with Perl 5.36.
395 .SS stringify
396 .IX Subsection "stringify"
397 .Vb 1
398 \& $str = stringify($val);
399 .Ve
400 .PP
401 This function is currently \fBexperimental\fR.
402 .PP
403 Returns a new plain perl string that represents the given argument.
404 .PP
405 When given a value that is already a string, a copy of this value is returned
406 unchanged. False booleans are treated like the empty string.
407 .PP
408 Numbers are turned into a decimal representation. True booleans are treated
409 like the number 1.
410 .PP
411 References to objects in classes that have overload and define the \f(CW""\fR
412 overload entry will use the delegated method to provide a value here.
413 .PP
414 Non\-object references, or references to objects in classes without a \f(CW""\fR
415 overload will return a string that names the underlying container type of
416 the reference, its memory address, and possibly its class name if it is an
417 object.
418 .PP
419 Available starting with Perl 5.40.
420 .SS ceil
421 .IX Subsection "ceil"
422 .Vb 1
423 \& $num = ceil($num);
424 .Ve
425 .PP
426 Returns the smallest integer value greater than or equal to the given
427 numerical argument.
428 .PP
429 Available starting with Perl 5.36. Since Perl 5.40, it is no longer
430 experimental and it is included in the 5.40 and higher builtin version
431 bundles.
432 .SS floor
433 .IX Subsection "floor"
434 .Vb 1
435 \& $num = floor($num);
436 .Ve
437 .PP
438 Returns the largest integer value less than or equal to the given numerical
439 argument.
440 .PP
441 Available starting with Perl 5.36. Since Perl 5.40, it is no longer
442 experimental and it is included in the 5.40 and higher builtin version
443 bundles.
444 .SS indexed
445 .IX Subsection "indexed"
446 .Vb 1
447 \& @ivpairs = indexed(@items)
448 .Ve
449 .PP
450 Returns an even\-sized list of number/value pairs, where each pair is formed
451 of a number giving an index in the original list followed by the value at that
452 position in it. I.e. returns a list twice the size of the original, being
453 equal to
454 .PP
455 .Vb 1
456 \& (0, $items[0], 1, $items[1], 2, $items[2], ...)
457 .Ve
458 .PP
459 Note that unlike the core \f(CW\*(C`values\*(C'\fR function, this function returns copies of
460 its original arguments, not aliases to them. Any modifications of these copies
461 are \fInot\fR reflected in modifications to the original.
462 .PP
463 .Vb 2
464 \& my @x = ...;
465 \& $_++ for indexed @x; # The @x array remains unaffected
466 .Ve
467 .PP
468 This function is primarily intended to be useful combined with multi\-variable
469 \&\f(CW\*(C`foreach\*(C'\fR loop syntax; as
470 .PP
471 .Vb 3
472 \& foreach my ($index, $value) (indexed LIST) {
473 \& ...
474 \& }
475 .Ve
476 .PP
477 In scalar context this function returns the size of the list that it would
478 otherwise have returned, and provokes a warning in the \f(CW\*(C`scalar\*(C'\fR category.
479 .PP
480 Available starting with Perl 5.36. Since Perl 5.40, it is no longer
481 experimental and it is included in the 5.40 and higher builtin version
482 bundles.
483 .SS trim
484 .IX Subsection "trim"
485 .Vb 1
486 \& $stripped = trim($string);
487 .Ve
488 .PP
489 Returns the input string with whitespace stripped from the beginning
490 and end. \fBtrim()\fR will remove these characters:
491 .PP
492 " ", an ordinary space.
493 .PP
494 "\et", a tab.
495 .PP
496 "\en", a new line (line feed).
497 .PP
498 "\er", a carriage return.
499 .PP
500 and all other Unicode characters that are flagged as whitespace.
501 A complete list is in "Whitespace" in perlrecharclass.
502 .PP
503 .Vb 4
504 \& $var = " Hello world "; # "Hello world"
505 \& $var = "\et\et\etHello world"; # "Hello world"
506 \& $var = "Hello world\en"; # "Hello world"
507 \& $var = "\ex{2028}Hello world\ex{3000}"; # "Hello world"
508 .Ve
509 .PP
510 \&\f(CW\*(C`trim\*(C'\fR is equivalent to:
511 .PP
512 .Vb 1
513 \& my $trimmed = $str =~ s/\eA\es+//ur =~ s/\es+\ez//ur;
514 .Ve
515 .PP
516 Available starting with Perl 5.36. Since Perl 5.40, it is no longer
517 experimental and it is included in the 5.40 and higher builtin version
518 bundles.
519 .SS is_tainted
520 .IX Subsection "is_tainted"
521 .Vb 1
522 \& $bool = is_tainted($var);
523 .Ve
524 .PP
525 Returns true when given a tainted variable.
526 .PP
527 Available starting with Perl 5.38.
528 .SS export_lexically
529 .IX Subsection "export_lexically"
530 .Vb 1
531 \& export_lexically($name1, $ref1, $name2, $ref2, ...)
532 .Ve
533 .PP
534 This function is currently \fBexperimental\fR.
535 .PP
536 Exports new lexical names into the scope currently being compiled. Names given
537 by the first of each pair of values will refer to the corresponding item whose
538 reference is given by the second. Types of item that are permitted are
539 subroutines, and scalar, array, and hash variables. If the item is a
540 subroutine, the name may optionally be prefixed with the \f(CW\*(C`&\*(C'\fR sigil, but for
541 convenience it doesn\*(Aqt have to. For items that are variables the sigil is
542 required, and must match the type of the variable.
543 .PP
544 .Vb 2
545 \& export_lexically func => \e&func,
546 \& \*(Aq&func\*(Aq => \e&func; # same as above
547 \&
548 \& export_lexically \*(Aq$scalar\*(Aq => \emy $var;
549 .Ve
550 .PP
551
552 .PP
553 .Vb 3
554 \& # The following are not permitted
555 \& export_lexically \*(Aq$var\*(Aq => \e@arr; # sigil does not match
556 \& export_lexically name => \e$scalar; # implied \*(Aq&\*(Aq sigil does not match
557 \&
558 \& export_lexically \*(Aq*name\*(Aq => \e*globref; # globrefs are not supported
559 .Ve
560 .PP
561 This must be called at compile time; which typically means during a \f(CW\*(C`BEGIN\*(C'\fR
562 block. Usually this would be used as part of an \f(CW\*(C`import\*(C'\fR method of a module,
563 when invoked as part of a \f(CW\*(C`use ...\*(C'\fR statement.
564 .PP
565 Available starting with Perl 5.38.
566 .SS load_module
567 .IX Subsection "load_module"
568 .Vb 1
569 \& load_module($module_name);
570 .Ve
571 .PP
572 This function is currently \fBexperimental\fR.
573 .PP
574 Loads a named module from the inclusion paths (\f(CW@INC\fR). \f(CW$module_name\fR must
575 be a string that provides a module name. It cannot be omitted, and providing
576 an invalid module name will result in an exception. Not providing any argument
577 results in a compilation error. Returns the loaded module\*(Aqs name on success.
578 .PP
579 The effect of \f(CW\*(C`load_module\*(C'\fR\-ing a module is mostly the same as \f(CW\*(C`require\*(C'\fR\-ing,
580 down to the same error conditions when the module does not exist, does not
581 compile, or does not evaluate to a true value. See also
582 the \f(CW\*(C`module_true\*(C'\fR feature.
583 .PP
584 \&\f(CW\*(C`load_module\*(C'\fR can\*(Aqt be used to require a particular version of Perl, nor can
585 it be given a bareword module name as an argument.
586 .PP
587 Available starting with Perl 5.40.
588 .SH "SEE ALSO"
589 .IX Header "SEE ALSO"
590 perlop, perlfunc, Scalar::Util, builtin::compat