Debian Codegraph @

upstream/debian-unstable/man3/builtin.3perl

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