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 trim
16 );
17
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 Individual named functions can be imported by listing them as import
27 parameters on the "use" statement for this pragma.
28 The overall "builtin" mechanism, as well as every individual function
30 it provides, are currently experimental.
31 Warning: At present, the entire "builtin" namespace is experimental.
33 Calling functions in it will trigger warnings of the
34 "experimental::builtin" category.
35 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 sub classify
42 {
43 my $val = shift;
44 use builtin 'is_bool';
46 return is_bool($val) ? "boolean" : "not a boolean";
47 }
48 # the is_bool() function is no longer visible here
50 # but may still be called by builtin::is_bool()
51 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 package An::Object::Class {
57 use builtin 'true', 'false';
58 ...
59 }
60 # does not appear as a method
62 An::Object::Class->true;
63 # Can't locate object method "true" via package "An::Object::Class"
65 # at ...
66
68 true
69 $val = true;
70 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 This gives an equivalent value to expressions like "!!1" or "!0".
77 false
79 $val = false;
80 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 This gives an equivalent value to expressions like "!!0" or "!1".
86 is_bool
88 $bool = is_bool($val);
89 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 This function used to be named "isbool". A compatibility alias is
98 provided currently but will be removed in a later version.
99 weaken
101 weaken($ref);
102 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 unweaken
109 unweaken($ref);
110 Strengthens a reference, undoing the effects of a previous call to
112 "weaken".
113 is_weak
115 $bool = is_weak($ref);
116 Returns true when given a weakened reference, or false if not a
118 reference or not weak.
119 This function used to be named "isweak". A compatibility alias is
121 provided currently but will be removed in a later version.
122 blessed
124 $str = blessed($ref);
125 Returns the package name for an object reference, or "undef" for a non-
127 reference or reference that is not an object.
128 refaddr
130 $num = refaddr($ref);
131 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 reftype
138 $str = reftype($ref);
139 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 created_as_string
146 $bool = created_as_string($val);
147 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 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 my $val = URI->new( "https://metacpan.org/" );
162 if( created_as_string $val ) { ... } # this will not execute
164 created_as_number
166 $bool = created_as_number($val);
167 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 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 my $val = Math::BigInt->new( 123 );
183 if( created_as_number $val ) { ... } # this will not execute
185 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 ceil
194 $num = ceil($num);
195 Returns the smallest integer value greater than or equal to the given
197 numerical argument.
198 floor
200 $num = floor($num);
201 Returns the largest integer value less than or equal to the given
203 numerical argument.
204 indexed
206 @ivpairs = indexed(@items)
207 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 (0, $items[0], 1, $items[1], 2, $items[2], ...)
214 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 my @x = ...;
221 $_++ for indexed @x; # The @x array remains unaffected
222 This function is primarily intended to be useful combined with multi-
224 variable "foreach" loop syntax; as
225 foreach my ($index, $value) (indexed LIST) {
227 ...
228 }
229 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 trim
235 $stripped = trim($string);
236 Returns the input string with whitespace stripped from the beginning
238 and end. trim() will remove these characters:
239 " ", an ordinary space.
241 "\t", a tab.
243 "\n", a new line (line feed).
245 "\r", a carriage return.
247 and all other Unicode characters that are flagged as whitespace. A
249 complete list is in "Whitespace" in perlrecharclass.
250 $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 "trim" is equivalent to:
257 $str =~ s/\A\s+|\s+\z//urg;
259 For Perl versions where this feature is not available look at the
261 String::Util module for a comparable implementation.
262
264 perlop, perlfunc, Scalar::Util
265perl v5.36.3 2023-11-30 builtin(3pm)