isa#

Test whether an object is an instance of a class or of any subclass derived from it.

isa is a binary operator, not a function. The left operand is an expression that should yield an object reference; the right operand names a class. It returns true when the left operand is a blessed reference whose class is — or inherits from — the class on the right. It returns false for anything else, including undef, unblessed references, and plain strings. It never throws.

Unlike the old UNIVERSAL::isa method, isa is safe to apply to arbitrary values: calling $x->isa("Foo") on a plain string that happens to name a class ($x = "Foo") invokes the class method and returns true, which is almost never what the caller meant. isa as an operator only reports true for blessed instances.

Synopsis#

use feature 'isa';          # or: use v5.36;

$obj isa Some::Class
$obj isa "Different::Class"
$obj isa $name_of_class

What you get back#

1 for a blessed object whose class is, or derives from, CLASS. The defined empty string "" (a false value that is numerically zero and exempt from uninitialized warnings) in every other case.

The operator never raises an exception: undefined, unreferenced, and misbranded values simply test false.

Feature gate#

isa is available from Perl 5.31.6 and became non-experimental in Perl 5.36. It is a lexical feature, enabled by either of:

use feature 'isa';
use v5.36;                  # enables the 5.36 feature bundle

Under no feature 'isa' (or in a scope that never enabled it), the bareword isa reverts to being a normal identifier, and the expression is a syntax error.

The right-hand side#

The right operand of isa is resolved to a class name at compile time when it is a bareword:

$obj isa Some::Class        # bareword — resolved at compile time

Any other expression is evaluated at runtime and must yield a string naming the class:

$obj isa "Different::Class" # string literal
$obj isa $class_name        # scalar variable
$obj isa (ref $other)       # any expression yielding a string

Barewords on the right side do not need to be declared, imported, or loaded; isa only consults the symbol table of CLASS to walk @ISA. A class that was never loaded simply has no parents, so $obj isa Unknown::Class just tests false.

Examples#

Basic instance check:

use feature 'isa';

package Animal { }
package Dog    { our @ISA = ('Animal'); }

my $rex = bless {}, 'Dog';

$rex isa Dog;               # true
$rex isa Animal;            # true — via @ISA
$rex isa Cat;               # false

Gate a method call on the actual class:

sub describe {
    my ($thing) = @_;
    return "unknown" unless $thing isa Animal;
    return $thing->sound;
}

Safe on arbitrary values — no exception on non-references:

undef      isa Animal;      # false
"Animal"   isa Animal;      # false — a string is not an instance
[]         isa Animal;      # false — unblessed ref
{}         isa Animal;      # false — unblessed ref
\&main::x  isa Animal;      # false — unblessed code ref

Dispatch on a class name captured at runtime:

for my $class (qw(Dog Cat Fish)) {
    if ($rex isa $class) {
        say "rex is a $class";
    }
}

Why isa is preferred over UNIVERSAL::isa as a method:

my $x = "Dog";
$x->isa('Dog');             # TRUE — string "Dog" is treated as a class name
$x isa Dog;                 # false — $x is not a blessed instance

The first form silently does the wrong thing on any string that happens to match a loaded class name. The operator form is type-aware and reports what the caller actually wanted to know.

Edge cases#

Left operand is undef: the operator returns false. No uninitialized warning is emitted — this is a deliberately quiet test.
Left operand is an unblessed reference: false. isa requires a blessed reference; array refs, hash refs, and code refs that have never been passed through bless fail the test.
Left operand is a plain string: false, even when the string matches a loaded class name. This is the behavioural split from UNIVERSAL::isa called as a method.
Right operand names an unknown class: the operator does not autoload or require the module. It walks the class’s @ISA; an unknown class has no @ISA, so the test is false.
Multiple inheritance: isa honours whatever method resolution order is active in the class (mro, c3 or the default depth-first search). The lookup is the same walk that method dispatch uses.
Reblessed objects: the test reflects the current blessing. Calling bless again on a reference changes what isa reports.
Parser precedence: isa is a non-associative named operator at the same precedence as the relational operators (lt, gt, le, ge). Chaining ($a isa B isa C) is a syntax error, as with the other relationals.
Feature not enabled: without use feature 'isa' (or use v5.36), the parser sees isa as an ordinary bareword and the expression fails to compile.
Right operand as a subroutine call: write it in parens. $obj isa some_class() parses; $obj isa some_class treats some_class as the literal class name (bareword).

Differences from upstream#

Fully compatible with upstream Perl 5.42.