内容

名称

builtin - Perl pragma 用于导入内置实用程序函数

语法

use builtin qw(
    true false is_bool
    weaken unweaken is_weak
    blessed refaddr reftype
    created_as_string created_as_number
    ceil floor
    indexed
    trim
    is_tainted
    export_lexically
);

说明

Perl 在 builtin 包中提供了多个实用程序函数。这些是普通函数，看起来和行为就像常规用户定义的函数一样。它们不提供新语法或不需要特殊解析。这些函数始终存在于解释器中，并且可以通过其完全限定名称随时调用。默认情况下，它们不可用作短名称，但可以出于方便而请求它们。

可以通过将单个命名函数列为此 pragma 的 use 语句上的导入参数来导入它们。

整个 builtin 机制以及它提供的每个单独函数目前都是实验性的。

警告：目前，整个builtin命名空间是实验性的。调用其中的函数将触发experimental::builtin类别的警告。

词法导入

此编译模块在当前编译范围内为这些内置函数创建词法别名。这类似于其他编译模块（如strict和feature）的词法效果。

sub classify
{
    my $val = shift;

    use builtin 'is_bool';
    return is_bool($val) ? "boolean" : "not a boolean";
}

# the is_bool() function is no longer visible here
# but may still be called by builtin::is_bool()

由于这些函数是通过词法导入的，而不是通过包符号导入的，因此用户无需采取任何特殊措施来确保它们不会意外地显示为某个类的对象方法。

package An::Object::Class {
    use builtin 'true', 'false';
    ...
}

# does not appear as a method
An::Object::Class->true;

# Can't locate object method "true" via package "An::Object::Class"
#   at ...

函数

true

$val = true;

返回布尔真值。虽然任何标量值都可以测试真值，并且大多数已定义、非空和非零的值都被 perl 视为“true”，但这个值很特殊，因为"is_bool"将其视为一个特殊布尔值。

这给出了等同于!!1或!0的表达式的值。

false

$val = false;

返回布尔假值。虽然任何非真标量值都被 perl 视为“false”，但这个值很特殊，因为"is_bool"将其视为一个特殊布尔值。

这给出了等同于!!0或!1的表达式的值。

is_bool

$bool = is_bool($val);

当给定一个特殊布尔值时返回 true，否则返回 false。特殊布尔值是任何布尔返回内置函数（如true或is_bool本身）、布尔返回运算符（如eq或==比较测试或!否定运算符）或包含其中一个结果的任何变量的结果。

此函数以前称为isbool。目前提供了一个兼容性别名，但将在以后的版本中删除。

weaken

weaken($ref);

弱化引用。弱引用不会增加其引用的引用计数。如果对引用的引用都已弱化，则引用将被释放，并且对它的所有剩余弱引用都将被设置为undef。

unweaken

unweaken($ref);

加强引用，撤消对"weaken"的先前调用的影响。

is_weak

$bool = is_weak($ref);

如果给定的是弱引用，则返回 true，如果不是引用或不是弱引用，则返回 false。

此函数以前称为 isweak。目前提供了一个兼容性别名，但将在以后的版本中删除。

blessed

$str = blessed($ref);

返回对象引用的包名称，或返回非引用或非对象引用的 undef。

refaddr

$num = refaddr($ref);

返回引用的内存地址，或返回非引用的 undef。此值对于纯 Perl 代码来说可能不太有用，但作为测试引用标识或唯一性的方法非常方便。

reftype

$str = reftype($ref);

返回引用的引用对象的容器基本类型，或返回非引用的 undef。它以全大写字符串的形式返回，例如数组引用的 ARRAY 或哈希引用的 HASH。

created_as_string

$bool = created_as_string($val);

返回一个布尔值，表示参数值最初是否创建为字符串。对于最近赋值或修改为字符串性质的任何标量表达式，它将返回 true - 例如从字符串文字赋值，或字符串操作（例如连接或正则表达式）的结果。对于引用（包括任何对象）、数字、布尔值和 undef，它将返回 false。

在 Perl 中的常规数据验证中，您不太可能希望使用它，因为它不会对仍然可以完美用作字符串的常规数字返回 true，也不会对任何对象引用返回 true - 尤其是重载字符串化运算符以尝试表现得更像字符串的对象。例如

my $val = URI->new( "https://metacpan.org/" );

if( created_as_string $val ) { ... }    # this will not execute

created_as_number

$bool = created_as_number($val);

返回一个布尔值，表示参数值最初是否创建为一个数字。对于任何标量表达式，如果其最近的赋值或修改是数值性质的，则它将返回 true - 例如从数字文字赋值，或加法等数值运算的结果。对于引用（包括任何对象）、字符串、布尔值和 undef，它将返回 false。

在 Perl 中，您不太可能希望将其用于常规数据验证，因为它不会对仍然可以完美用作数字的十进制数字的常规字符串返回 true，也不会对任何对象引用返回 true - 尤其是重载 numification 运算符以尝试表现得更像数字的对象。例如

my $val = Math::BigInt->new( 123 );

if( created_as_number $val ) { ... }    # this will not execute

虽然大多数 Perl 代码应该对标量值进行操作，而无需了解其创建历史记录，但这两个函数旨在供 JSON 编码器等数据序列化模块或类似情况使用，在这些情况下，语言互操作性问题需要区分本质上类似于字符串的值和类似于数字的值。

ceil

$num = ceil($num);

返回大于或等于给定数值参数的最小整数值。

floor

$num = floor($num);

返回小于或等于给定数值参数的最大整数值。

indexed

@ivpairs = indexed(@items)

返回一个偶数大小的数字/值对列表，其中每对由一个数字（给出了原始列表中的索引）和该位置的值组成。即返回一个大小是原始列表两倍的列表，等于

(0, $items[0], 1, $items[1], 2, $items[2], ...)

请注意，与核心 values 函数不同，此函数返回其原始参数的副本，而不是它们的别名。对这些副本的任何修改不会反映在对原件的修改中。

my @x = ...;
$_++ for indexed @x;  # The @x array remains unaffected

此函数主要旨在与多变量 foreach 循环语法结合使用；如

foreach my ($index, $value) (indexed LIST) {
    ...
}

在标量上下文中，此函数返回它原本会返回的列表的大小，并在 scalar 类别中引发警告。

trim

$stripped = trim($string);

返回从开头和结尾删除空格的输入字符串。trim() 将删除以下字符

" "，一个普通空格。

"\t"，一个制表符。

"\n"，一个换行符（换行符）。

"\r"，一个回车符。

以及所有其他标记为 whitespace 的 Unicode 字符。完整列表在 "Whitespace" in perlrecharclass 中。

$var = "  Hello world   ";            # "Hello world"
$var = "\t\t\tHello world";           # "Hello world"
$var = "Hello world\n";               # "Hello world"
$var = "\x{2028}Hello world\x{3000}"; # "Hello world"

trim 等于

$str =~ s/\A\s+|\s+\z//urg;

对于此功能不可用的 Perl 版本，请查看 String::Util 模块，以获得可比的实现。

is_tainted

$bool = is_tainted($var);

当给定一个已污染的变量时，返回 true。

export_lexically

export_lexically($name1, $ref1, $name2, $ref2, ...)

将新的词法名称导出到当前正在编译的范围中。每个值对中的第一个值给出的名称将引用第二个值给出的引用的相应项。允许的项类型包括子例程以及标量、数组和哈希变量。如果该项是一个子例程，则该名称可以选择带有 & sigil 前缀，但为方便起见，它不必这样做。对于变量项，sigil 是必需的，并且必须与变量的类型匹配。

export_lexically func    => \&func,
                 '&func' => \&func;  # same as above

export_lexically '$scalar' => \my $var;

# The following are not permitted
export_lexically '$var' => \@arr;   # sigil does not match
export_lexically name => \$scalar;  # implied '&' sigil does not match

export_lexically '*name' => \*globref;  # globrefs are not supported

这必须在编译时调用；这通常意味着在 BEGIN 块期间。通常，这将用作模块的 import 方法的一部分，当作为 use ... 语句的一部分调用时。

另请参阅

perlop、perlfunc、Scalar::Util