1builtin(3pm)           Perl Programmers Reference Guide           builtin(3pm)
2
3
4

NAME

6       builtin - Perl pragma to import built-in utility functions
7

SYNOPSIS

9           use builtin qw(
10               true false is_bool
11               weaken unweaken is_weak
12               blessed refaddr reftype
13               created_as_string created_as_number
14               ceil floor
15               trim
16           );
17

DESCRIPTION

19       Perl provides several utility functions in the "builtin" package. These
20       are plain functions, and look and behave just like regular user-defined
21       functions do. They do not provide new syntax or require special
22       parsing. These functions are always present in the interpreter and can
23       be called at any time by their fully-qualified names. By default they
24       are not available as short names, but can be requested for convenience.
25
26       Individual named functions can be imported by listing them as import
27       parameters on the "use" statement for this pragma.
28
29       The overall "builtin" mechanism, as well as every individual function
30       it provides, are currently experimental.
31
32       Warning:  At present, the entire "builtin" namespace is experimental.
33       Calling functions in it will trigger warnings of the
34       "experimental::builtin" category.
35
36   Lexical Import
37       This pragma module creates lexical aliases in the currently-compiling
38       scope to these builtin functions. This is similar to the lexical effect
39       of other pragmas such as strict and feature.
40
41           sub classify
42           {
43               my $val = shift;
44
45               use builtin 'is_bool';
46               return is_bool($val) ? "boolean" : "not a boolean";
47           }
48
49           # the is_bool() function is no longer visible here
50           # but may still be called by builtin::is_bool()
51
52       Because these functions are imported lexically, rather than by package
53       symbols, the user does not need to take any special measures to ensure
54       they don't accidentally appear as object methods from a class.
55
56           package An::Object::Class {
57               use builtin 'true', 'false';
58               ...
59           }
60
61           # does not appear as a method
62           An::Object::Class->true;
63
64           # Can't locate object method "true" via package "An::Object::Class"
65           #   at ...
66

FUNCTIONS

68   true
69           $val = true;
70
71       Returns the boolean truth value. While any scalar value can be tested
72       for truth and most defined, non-empty and non-zero values are
73       considered "true" by perl, this one is special in that "is_bool"
74       considers it to be a distinguished boolean value.
75
76       This gives an equivalent value to expressions like "!!1" or "!0".
77
78   false
79           $val = false;
80
81       Returns the boolean fiction value. While any non-true scalar value is
82       considered "false" by perl, this one is special in that "is_bool"
83       considers it to be a distinguished boolean value.
84
85       This gives an equivalent value to expressions like "!!0" or "!1".
86
87   is_bool
88           $bool = is_bool($val);
89
90       Returns true when given a distinguished boolean value, or false if not.
91       A distinguished boolean value is the result of any boolean-returning
92       builtin function (such as "true" or "is_bool" itself), boolean-
93       returning operator (such as the "eq" or "==" comparison tests or the
94       "!" negation operator), or any variable containing one of these
95       results.
96
97       This function used to be named "isbool". A compatibility alias is
98       provided currently but will be removed in a later version.
99
100   weaken
101           weaken($ref);
102
103       Weakens a reference. A weakened reference does not contribute to the
104       reference count of its referent. If only weakened references to a
105       referent remain, it will be disposed of, and all remaining weak
106       references to it will have their value set to "undef".
107
108   unweaken
109           unweaken($ref);
110
111       Strengthens a reference, undoing the effects of a previous call to
112       "weaken".
113
114   is_weak
115           $bool = is_weak($ref);
116
117       Returns true when given a weakened reference, or false if not a
118       reference or not weak.
119
120       This function used to be named "isweak". A compatibility alias is
121       provided currently but will be removed in a later version.
122
123   blessed
124           $str = blessed($ref);
125
126       Returns the package name for an object reference, or "undef" for a non-
127       reference or reference that is not an object.
128
129   refaddr
130           $num = refaddr($ref);
131
132       Returns the memory address for a reference, or "undef" for a non-
133       reference.  This value is not likely to be very useful for pure Perl
134       code, but is handy as a means to test for referential identity or
135       uniqueness.
136
137   reftype
138           $str = reftype($ref);
139
140       Returns the basic container type of the referent of a reference, or
141       "undef" for a non-reference. This is returned as a string in all-
142       capitals, such as "ARRAY" for array references, or "HASH" for hash
143       references.
144
145   created_as_string
146           $bool = created_as_string($val);
147
148       Returns a boolean representing if the argument value was originally
149       created as a string. It will return true for any scalar expression
150       whose most recent assignment or modification was of a string-like
151       nature - such as assignment from a string literal, or the result of a
152       string operation such as concatenation or regexp. It will return false
153       for references (including any object), numbers, booleans and undef.
154
155       It is unlikely that you will want to use this for regular data
156       validation within Perl, as it will not return true for regular numbers
157       that are still perfectly usable as strings, nor for any object
158       reference - especially objects that overload the stringification
159       operator in an attempt to behave more like strings. For example
160
161           my $val = URI->new( "https://metacpan.org/" );
162
163           if( created_as_string $val ) { ... }    # this will not execute
164
165   created_as_number
166           $bool = created_as_number($val);
167
168       Returns a boolean representing if the argument value was originally
169       created as a number. It will return true for any scalar expression
170       whose most recent assignment or modification was of a numerical nature
171       - such as assignment from a number literal, or the result of a
172       numerical operation such as addition. It will return false for
173       references (including any object), strings, booleans and undef.
174
175       It is unlikely that you will want to use this for regular data
176       validation within Perl, as it will not return true for regular strings
177       of decimal digits that are still perfectly usable as numbers, nor for
178       any object reference - especially objects that overload the
179       numification operator in an attempt to behave more like numbers. For
180       example
181
182           my $val = Math::BigInt->new( 123 );
183
184           if( created_as_number $val ) { ... }    # this will not execute
185
186       While most Perl code should operate on scalar values without needing to
187       know their creation history, these two functions are intended to be
188       used by data serialisation modules such as JSON encoders or similar
189       situations, where language interoperability concerns require making a
190       distinction between values that are fundamentally stringlike versus
191       numberlike in nature.
192
193   ceil
194           $num = ceil($num);
195
196       Returns the smallest integer value greater than or equal to the given
197       numerical argument.
198
199   floor
200           $num = floor($num);
201
202       Returns the largest integer value less than or equal to the given
203       numerical argument.
204
205   indexed
206           @ivpairs = indexed(@items)
207
208       Returns an even-sized list of number/value pairs, where each pair is
209       formed of a number giving an index in the original list followed by the
210       value at that position in it.  I.e. returns a list twice the size of
211       the original, being equal to
212
213           (0, $items[0], 1, $items[1], 2, $items[2], ...)
214
215       Note that unlike the core "values" function, this function returns
216       copies of its original arguments, not aliases to them. Any
217       modifications of these copies are not reflected in modifications to the
218       original.
219
220           my @x = ...;
221           $_++ for indexed @x;  # The @x array remains unaffected
222
223       This function is primarily intended to be useful combined with multi-
224       variable "foreach" loop syntax; as
225
226           foreach my ($index, $value) (indexed LIST) {
227               ...
228           }
229
230       In scalar context this function returns the size of the list that it
231       would otherwise have returned, and provokes a warning in the "scalar"
232       category.
233
234   trim
235           $stripped = trim($string);
236
237       Returns the input string with whitespace stripped from the beginning
238       and end. trim() will remove these characters:
239
240       " ", an ordinary space.
241
242       "\t", a tab.
243
244       "\n", a new line (line feed).
245
246       "\r", a carriage return.
247
248       and all other Unicode characters that are flagged as whitespace.  A
249       complete list is in "Whitespace" in perlrecharclass.
250
251           $var = "  Hello world   ";            # "Hello world"
252           $var = "\t\t\tHello world";           # "Hello world"
253           $var = "Hello world\n";               # "Hello world"
254           $var = "\x{2028}Hello world\x{3000}"; # "Hello world"
255
256       "trim" is equivalent to:
257
258           $str =~ s/\A\s+|\s+\z//urg;
259
260       For Perl versions where this feature is not available look at the
261       String::Util module for a comparable implementation.
262

SEE ALSO

264       perlop, perlfunc, Scalar::Util
265
266
267
268perl v5.36.0                      2022-08-30                      builtin(3pm)
Impressum