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