1builtin(3pm) Perl Programmers Reference Guide builtin(3pm)
2
6 builtin - Perl pragma to import built-in utility functions
7
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 indexed
16 trim
17 is_tainted
18 export_lexically
19 );
20
22 Perl provides several utility functions in the "builtin" package. These
23 are plain functions, and look and behave just like regular user-defined
24 functions do. They do not provide new syntax or require special
25 parsing. These functions are always present in the interpreter and can
26 be called at any time by their fully-qualified names. By default they
27 are not available as short names, but can be requested for convenience.
28 Individual named functions can be imported by listing them as import
30 parameters on the "use" statement for this pragma.
31 The overall "builtin" mechanism, as well as every individual function
33 it provides, are currently experimental.
34 Warning: At present, the entire "builtin" namespace is experimental.
36 Calling functions in it will trigger warnings of the
37 "experimental::builtin" category.
38 Lexical Import
40 This pragma module creates lexical aliases in the currently-compiling
41 scope to these builtin functions. This is similar to the lexical effect
42 of other pragmas such as strict and feature.
43 sub classify
45 {
46 my $val = shift;
47 use builtin 'is_bool';
49 return is_bool($val) ? "boolean" : "not a boolean";
50 }
51 # the is_bool() function is no longer visible here
53 # but may still be called by builtin::is_bool()
54 Because these functions are imported lexically, rather than by package
56 symbols, the user does not need to take any special measures to ensure
57 they don't accidentally appear as object methods from a class.
58 package An::Object::Class {
60 use builtin 'true', 'false';
61 ...
62 }
63 # does not appear as a method
65 An::Object::Class->true;
66 # Can't locate object method "true" via package "An::Object::Class"
68 # at ...
69
71 true
72 $val = true;
73 Returns the boolean truth value. While any scalar value can be tested
75 for truth and most defined, non-empty and non-zero values are
76 considered "true" by perl, this one is special in that "is_bool"
77 considers it to be a distinguished boolean value.
78 This gives an equivalent value to expressions like "!!1" or "!0".
80 false
82 $val = false;
83 Returns the boolean fiction value. While any non-true scalar value is
85 considered "false" by perl, this one is special in that "is_bool"
86 considers it to be a distinguished boolean value.
87 This gives an equivalent value to expressions like "!!0" or "!1".
89 is_bool
91 $bool = is_bool($val);
92 Returns true when given a distinguished boolean value, or false if not.
94 A distinguished boolean value is the result of any boolean-returning
95 builtin function (such as "true" or "is_bool" itself), boolean-
96 returning operator (such as the "eq" or "==" comparison tests or the
97 "!" negation operator), or any variable containing one of these
98 results.
99 This function used to be named "isbool". A compatibility alias is
101 provided currently but will be removed in a later version.
102 weaken
104 weaken($ref);
105 Weakens a reference. A weakened reference does not contribute to the
107 reference count of its referent. If only weakened references to a
108 referent remain, it will be disposed of, and all remaining weak
109 references to it will have their value set to "undef".
110 unweaken
112 unweaken($ref);
113 Strengthens a reference, undoing the effects of a previous call to
115 "weaken".
116 is_weak
118 $bool = is_weak($ref);
119 Returns true when given a weakened reference, or false if not a
121 reference or not weak.
122 This function used to be named "isweak". A compatibility alias is
124 provided currently but will be removed in a later version.
125 blessed
127 $str = blessed($ref);
128 Returns the package name for an object reference, or "undef" for a non-
130 reference or reference that is not an object.
131 refaddr
133 $num = refaddr($ref);
134 Returns the memory address for a reference, or "undef" for a non-
136 reference. This value is not likely to be very useful for pure Perl
137 code, but is handy as a means to test for referential identity or
138 uniqueness.
139 reftype
141 $str = reftype($ref);
142 Returns the basic container type of the referent of a reference, or
144 "undef" for a non-reference. This is returned as a string in all-
145 capitals, such as "ARRAY" for array references, or "HASH" for hash
146 references.
147 created_as_string
149 $bool = created_as_string($val);
150 Returns a boolean representing if the argument value was originally
152 created as a string. It will return true for any scalar expression
153 whose most recent assignment or modification was of a string-like
154 nature - such as assignment from a string literal, or the result of a
155 string operation such as concatenation or regexp. It will return false
156 for references (including any object), numbers, booleans and undef.
157 It is unlikely that you will want to use this for regular data
159 validation within Perl, as it will not return true for regular numbers
160 that are still perfectly usable as strings, nor for any object
161 reference - especially objects that overload the stringification
162 operator in an attempt to behave more like strings. For example
163 my $val = URI->new( "https://metacpan.org/" );
165 if( created_as_string $val ) { ... } # this will not execute
167 created_as_number
169 $bool = created_as_number($val);
170 Returns a boolean representing if the argument value was originally
172 created as a number. It will return true for any scalar expression
173 whose most recent assignment or modification was of a numerical nature
174 - such as assignment from a number literal, or the result of a
175 numerical operation such as addition. It will return false for
176 references (including any object), strings, booleans and undef.
177 It is unlikely that you will want to use this for regular data
179 validation within Perl, as it will not return true for regular strings
180 of decimal digits that are still perfectly usable as numbers, nor for
181 any object reference - especially objects that overload the
182 numification operator in an attempt to behave more like numbers. For
183 example
184 my $val = Math::BigInt->new( 123 );
186 if( created_as_number $val ) { ... } # this will not execute
188 While most Perl code should operate on scalar values without needing to
190 know their creation history, these two functions are intended to be
191 used by data serialisation modules such as JSON encoders or similar
192 situations, where language interoperability concerns require making a
193 distinction between values that are fundamentally stringlike versus
194 numberlike in nature.
195 ceil
197 $num = ceil($num);
198 Returns the smallest integer value greater than or equal to the given
200 numerical argument.
201 floor
203 $num = floor($num);
204 Returns the largest integer value less than or equal to the given
206 numerical argument.
207 indexed
209 @ivpairs = indexed(@items)
210 Returns an even-sized list of number/value pairs, where each pair is
212 formed of a number giving an index in the original list followed by the
213 value at that position in it. I.e. returns a list twice the size of
214 the original, being equal to
215 (0, $items[0], 1, $items[1], 2, $items[2], ...)
217 Note that unlike the core "values" function, this function returns
219 copies of its original arguments, not aliases to them. Any
220 modifications of these copies are not reflected in modifications to the
221 original.
222 my @x = ...;
224 $_++ for indexed @x; # The @x array remains unaffected
225 This function is primarily intended to be useful combined with multi-
227 variable "foreach" loop syntax; as
228 foreach my ($index, $value) (indexed LIST) {
230 ...
231 }
232 In scalar context this function returns the size of the list that it
234 would otherwise have returned, and provokes a warning in the "scalar"
235 category.
236 trim
238 $stripped = trim($string);
239 Returns the input string with whitespace stripped from the beginning
241 and end. trim() will remove these characters:
242 " ", an ordinary space.
244 "\t", a tab.
246 "\n", a new line (line feed).
248 "\r", a carriage return.
250 and all other Unicode characters that are flagged as whitespace. A
252 complete list is in "Whitespace" in perlrecharclass.
253 $var = " Hello world "; # "Hello world"
255 $var = "\t\t\tHello world"; # "Hello world"
256 $var = "Hello world\n"; # "Hello world"
257 $var = "\x{2028}Hello world\x{3000}"; # "Hello world"
258 "trim" is equivalent to:
260 $str =~ s/\A\s+|\s+\z//urg;
262 For Perl versions where this feature is not available look at the
264 String::Util module for a comparable implementation.
265 is_tainted
267 $bool = is_tainted($var);
268 Returns true when given a tainted variable.
270 export_lexically
272 export_lexically($name1, $ref1, $name2, $ref2, ...)
273 Exports new lexical names into the scope currently being compiled.
275 Names given by the first of each pair of values will refer to the
276 corresponding item whose reference is given by the second. Types of
277 item that are permitted are subroutines, and scalar, array, and hash
278 variables. If the item is a subroutine, the name may optionally be
279 prefixed with the "&" sigil, but for convenience it doesn't have to.
280 For items that are variables the sigil is required, and must match the
281 type of the variable.
282 export_lexically func => \&func,
284 '&func' => \&func; # same as above
285 export_lexically '$scalar' => \my $var;
287 # The following are not permitted
289 export_lexically '$var' => \@arr; # sigil does not match
290 export_lexically name => \$scalar; # implied '&' sigil does not match
291 export_lexically '*name' => \*globref; # globrefs are not supported
293 This must be called at compile time; which typically means during a
295 "BEGIN" block. Usually this would be used as part of an "import" method
296 of a module, when invoked as part of a "use ..." statement.
297
299 perlop, perlfunc, Scalar::Util
300perl v5.38.2 2023-11-30 builtin(3pm)