builtin

(原始碼, CPAN)

版本 0.008

#名稱

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 會將大多數已定義、非空和非零的值視為「真」，但此值很特別，因為 "is_bool" 會將它視為一個區別的布林值。

這會傳回等同於 !!1 或 !0 等運算式的值。

#false

$val = false;

傳回布林假值。雖然 perl 會將任何非真標量值視為「假」，但此值很特別，因為 "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，特別是嘗試透過重載數字化運算子來表現得更像數字的物件。例如

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"，一個回車符。

以及所有標記為空白字元的其他 Unicode 字元。完整清單請參閱 "空白字元" 中的 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, ...)

匯出新的詞彙名稱到目前正在編譯的範圍。由每一對值的第一個給定的名稱將參照由第二個給定的參考對應的項目。允許的項目類型包括子常式、以及標量、陣列和雜湊變數。如果項目是子常式，名稱可以選擇性地加上 & 標記作為前綴，但為了方便起見，它不必這樣做。對於變數項目，標記是必需的，且必須與變數的類型相符。

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

目錄

#名稱

#語法

#說明