method is-initial-thread§

method is-initial-thread(--> Bool)

Returns a Bool indicating whether the current thread (if called as a class method) or the Thread object on which it is called, is the initial thread the program started on.

say Thread.is-initial-thread;    # True if this is the initial thread
say $*THREAD.is-initial-thread;  # True if $*THREAD is the initial thread

Please note there is no guarantee that this is actually the main thread from the OS's point of view. Also note that if you need this other than from a pure introspection / debugging point of view, that there are probably better ways to achieve what you're trying to achieve.

method is-win§

Instance method returning a Bool indicating whether the distribution is a version of the Windows operating system.

method is_trusted§

method is_trusted($type, $claimant)

Returns 1 if $type trusts $claimant, and 0 otherwise. Types always trust themselves.

method is_type§

method is_type(Mu \obj, Mu \type --> Bool:D)

Type-checks obj against type

method is-setting§

method is-setting(Backtrace::Frame:D: --> Bool:D)

Returns True if the frame is part of a setting.

my $bt = Backtrace.new;
my $btf = $bt[0];
say $btf.is-setting; # OUTPUT: «True␤»

method is-routine§

method is-routine(Backtrace::Frame:D: --> Bool:D)

Return True if the frame points into a routine (and not into a mere Block).

my $bt = Backtrace.new;
my $btf = $bt[0];
say $btf.is-routine;

method is-hidden§

method is-hidden(Backtrace::Frame:D: --> Bool:D)

Returns True if the frame is marked as hidden with the is hidden-from-backtrace trait.

my $bt = Backtrace.new;
my $btf = $bt[0];
say $btf.is-hidden;

method is-implementation-detail§

method is-implementation-detail(--> False)

Note: this method has been available in Rakudo compiler starting from 2020.05 release.

Returns True if the code object was marked with is implementation-detail trait, False otherwise.

method is-absolute§

method is-absolute(Str:D $path --> Bool:D)

Returns True if the $path starts with a slash ("/") or backslash ("\"), even if they have combining character on them, optionally preceded by a volume:

say IO::Spec::Win32.is-absolute: "/foo";        # OUTPUT: «True␤»
say IO::Spec::Win32.is-absolute: "/\x[308]foo"; # OUTPUT: «True␤»
say IO::Spec::Win32.is-absolute: ｢C:\foo｣;      # OUTPUT: «True␤»
say IO::Spec::Win32.is-absolute: "bar";         # OUTPUT: «False␤»

sub is-approx-calculate§

sub is-approx-calculate($got, $expected, $abs-tol where { !.defined or $_ >= 0 },
                        $rel-tol where { !.defined or $_ >= 0 }, $desc)

This is the actual routine called by is-approx when absolute and relative tolerance are specified. They are tested independently, and the test succeeds only if both pass.

sub is-deeply§

multi is-deeply(Seq:D $got, Seq:D $expected, $reason = '')
multi is-deeply(Seq:D $got, Mu $expected, $reason = '')
multi is-deeply(Mu $got, Seq:D $expected, $reason = '')
multi is-deeply(Mu $got, Mu $expected, $reason = '')

Marks a test as passed if the first and second parameters are equivalent, using the same semantics as the eqv operator. This is the best way to check for equality of (deep) data structures. The function accepts an optional description of the test as the last argument.

use Test;
plan 1;

sub string-info(Str() $_) {
    Map.new: (
      length  =>  .chars,
      char-counts => Bag.new-from-pairs: (
          letters => +.comb(/<:letter>/),
          digits  => +.comb(/<:digit>/),
          other   => +.comb(/<.-:letter-:digit>/),
    ))
}

is-deeply string-info('42 Butterflies ♥ Raku'), Map.new((
    :21length,
    char-counts => Bag.new-from-pairs: ( :15letters, :2digits, :4other, )
)), 'string-info gives right info';

Note: for historical reasons, Seq:D arguments to is-deeply get converted to Lists by calling .cache on them. If you want to ensure strict Seq comparisons, use cmp-ok $got, 'eqv', $expected, $desc instead.

sub is-approx§

multi is-approx(Numeric $got, Numeric $expected, $desc = '')

multi is-approx(Numeric $got, Numeric $expected, Numeric $abs-tol,
                    $desc = '')

multi is-approx(Numeric $got, Numeric $expected, $desc = '',
                    Numeric :$rel-tol is required)

multi is-approx(Numeric $got, Numeric $expected, $desc = '',
                    Numeric :$abs-tol is required)

multi is-approx(Numeric $got, Numeric $expected, $desc = '',
                    Numeric :$rel-tol is required,
                    Numeric :$abs-tol is required)

Marks a test as passed if the $got and $expected numerical values are approximately equal to each other. The subroutine can be called in numerous ways that let you test using relative tolerance ($rel-tol) or absolute tolerance ($abs-tol) of different values.

If no tolerance is set, the function will base the tolerance on the absolute value of $expected: if it's smaller than 1e-6, use absolute tolerance of 1e-5; if it's larger, use relative tolerance of 1e-6.

my Numeric ($value, $expected, $abs-tol, $rel-tol) = ...

is-approx $value, $expected;
is-approx $value, $expected, 'test description';

is-approx $value, $expected, $abs-tol;
is-approx $value, $expected, $abs-tol, 'test description';

is-approx $value, $expected, :$rel-tol;
is-approx $value, $expected, :$rel-tol, 'test description';

is-approx $value, $expected, :$abs-tol;
is-approx $value, $expected, :$abs-tol, 'test description';

is-approx $value, $expected, :$abs-tol, :$rel-tol;
is-approx $value, $expected, :$abs-tol, :$rel-tol, 'test description';

Absolute tolerance§

When an absolute tolerance is set, it's used as the actual maximum value by which the first and the second parameters can differ. For example:

is-approx 3, 4, 2; # success
is-approx 3, 6, 2; # fail

is-approx 300, 302, 2; # success
is-approx 300, 400, 2; # fail
is-approx 300, 600, 2; # fail

Regardless of values given, the difference between them cannot be more than 2.

Relative tolerance§

When a relative tolerance is set, the test checks the relative difference between values. Given the same tolerance, the larger the numbers given, the larger the value they can differ by can be.

For example:

is-approx 10, 10.5, :rel-tol<0.1>; # success
is-approx 10, 11.5, :rel-tol<0.1>; # fail

is-approx 100, 105, :rel-tol<0.1>; # success
is-approx 100, 115, :rel-tol<0.1>; # fail

Both versions use 0.1 for relative tolerance, yet the first can differ by about 1 while the second can differ by about 10. The function used to calculate the difference is:

              |value - expected|
⁣rel-diff = ────────────────────────
           max(|value|, |expected|)

and the test will fail if rel-diff is higher than $rel-tol.

Both absolute and relative tolerance specified§

is-approx $value, $expected, :rel-tol<.5>, :abs-tol<10>;

When both absolute and relative tolerances are specified, each will be tested independently, and the is-approx test will succeed only if both pass.

sub is_approx§

multi is_approx(Mu $got, Mu $expected, $desc = '')

NOTE: Removed with Rakudo release 2023.09, deprecated in older versions. Use is-approx instead.

sub is§

multi is(Mu $got, Mu:U $expected, $desc = '')
multi is(Mu $got, Mu:D $expected, $desc = '')

Marks a test as passed if $got and $expected compare positively with the eq operator, unless $expected is a type object, in which case === operator will be used instead; accepts an optional description of the test as the last argument.

NOTE: the eq operator stringifies its operands, which means is() is not a good function for testing more complex things, such as lists: is (1, (2, (3,))), [1, 2, 3] passes the test, even though the operands are vastly different. For those cases, use is-deeply routine

my $pdf-document; sub factorial($x) { ... }; ...;
is $pdf-document.author, "Joe", 'Retrieving the author field';
is factorial(6),         720,   'Factorial - small integer';
my Int $a;
is $a, Int, 'The variable $a is an unassigned Int';

Note: if only whitespace differs between the values, is() will output failure message differently, to show the whitespace in each values. For example, in the output below, the second test shows the literal \t in the got: line:

is "foo\tbar", "foo\tbaz";   # expected: 'foo     baz'␤#      got: 'foo   bar'
is "foo\tbar", "foo    bar"; # expected: "foo    bar"␤#      got: "foo\tbar"

routine is-prime§

multi        is-prime (Int:D $number --> Bool:D)
multi method is-prime (Int:D: --> Bool:D)

Returns True if this Int is known to be a prime, or is likely to be a prime based on a probabilistic Miller-Rabin test.

Returns False if this Int is known not to be a prime.

say 2.is-prime;         # OUTPUT: «True␤»
say is-prime(9);        # OUTPUT: «False␤»

method is-relative§

method is-relative(IO::Path:D: --> Bool)

Returns True if the path is a relative path, and False otherwise. Windows caveats for .is-absolute apply.

method is-absolute§

method is-absolute(IO::Path:D: --> Bool)

Returns True if the path is an absolute path, and False otherwise.

"/foo".IO.is-absolute.say; # OUTPUT: «True␤»
"bars".IO.is-absolute.say; # OUTPUT: «False␤»

Note that on Windows a path that starts with a slash or backslash is still considered absolute even if no volume was given, as it is absolute for that particular volume:

IO::Path::Win32.new("/foo"  ).is-absolute.say; # OUTPUT: «True␤»
IO::Path::Win32.new("C:/foo").is-absolute.say; # OUTPUT: «True␤»
IO::Path::Win32.new("C:foo" ).is-absolute.say; # OUTPUT: «False␤»

method is-lazy§

method is-lazy(--> False )

Returns False.

method is-lazy§

method is-lazy(Seq:D:)

Returns True if and only if the underlying iterator or cached list considers itself lazy. If called on an already consumed sequence, throws an error of type X::Seq::Consumed.

method is-monotonically-increasing§

method is-monotonically-increasing(Iterator:D: --> Bool:D)

Should return True for iterators that, given a source, will always produce the values in the increasing value (according to cmp semantics).

Built-in operations can perform certain optimizations when it is certain that values will always be produced in ascending order. Some examples:

say (1..10).iterator.is-monotonically-increasing;              # OUTPUT: «True␤»
say (1..10).roll(5).iterator.is-monotonically-increasing;      # OUTPUT: «False␤»
say %(a => 42, b => 137).iterator.is-monotonically-increasing; # OUTPUT: «False␤»

The Iterator role implements this method returning False, indicating an iterator that will not produce values with increasing values.

method is-deterministic§

method is-deterministic(Iterator:D: --> Bool:D)

Should return True for iterators that, given a source, will always produce the values in the same order.

Built-in operations can perform certain optimizations when it is certain that values will always be produced in the same order. Some examples:

say (1..10).iterator.is-deterministic;              # OUTPUT: «True␤»
say (1..10).roll(5).iterator.is-deterministic;      # OUTPUT: «False␤»
say %(a => 42, b => 137).iterator.is-deterministic; # OUTPUT: «False␤»

The Iterator role implements this method returning True, indicating an iterator that will always produce values in the same order.

method is-lazy§

method is-lazy(Iterator:D: --> Bool:D)

Should return True for iterators that consider themselves lazy, and False otherwise.

Built-in operations that know that they can produce infinitely many values return True here, for example (1..6).roll(*).

say (1 .. 100).iterator.is-lazy; # OUTPUT: «False␤»
say (1 .. ∞).iterator.is-lazy; # OUTPUT: «True␤»

The Iterator role implements this method returning False, indicating a non-lazy iterator.

method is-leap-year§

method is-leap-year(Dateish:D: --> Bool:D)

Returns True if the year of the Dateish object is a leap year.

say DateTime.new(:year<2016>).is-leap-year; # OUTPUT: «True␤»
say Date.new("1900-01-01").is-leap-year;    # OUTPUT: «False␤»

method is-lazy§

method is-lazy(--> False )

Returns False.

method is-absolute§

method is-absolute(Str:D $path --> Bool:D)

Returns True if the $path starts with a slash ("/"), even if it has combining character on it:

say IO::Spec::Unix.is-absolute: "/foo";        # OUTPUT: «True␤»
say IO::Spec::Unix.is-absolute: "/\x[308]foo"; # OUTPUT: «True␤»
say IO::Spec::Unix.is-absolute: "bar";         # OUTPUT: «False␤»

method is-wrapped§

method is-wrapped()

Returns True or False, depending on the whether or not the Routine is wrapped.

The is trait§

proto trait_mod:<is>(Mu $, |) {*}

is applies to any kind of scalar object, and can take any number of named or positional arguments. It is the most commonly used trait, and takes the following forms, depending on the type of the first argument.

is applied to classes.§

The most common form, involving two classes, one that is being defined and the other existing, defines parenthood. A is B, if both are classes, defines A as a subclass of B.

is DEPRECATED can be applied to classes, Attributes or Routines, marks them as deprecated and issues a message, if provided.

Several instances of is are translated directly into attributes for the class they refer to: rw, nativesize, ctype, unsigned, hidden, array_type.

The Uninstantiable representation trait is not so much related to the representation as related to what can be done with a specific class; it effectively prevents the creation of instances of the class in any possible way.

constant @IMM = <Innie Minnie Moe>;

class don't-instantiate is repr('Uninstantiable') {
    my $.counter;

    method imm () {
        return @IMM[ $.counter++ mod @IMM.elems ];
    }
}
say don't-instantiate.imm for ^10;

Uninstantiable classes can still be used via their class variables and methods, as above. However, trying to instantiate them this way: my $do-instantiate = don't-instantiate.new; will yield the error You cannot create an instance of this type (don't-instantiate).

is repr and native representations.§

Since the is trait refers, in general, to the nature of the class or object they are applied to, they are used extensively in native calls to specify the representation of the data structures that are going to be handled by the native functions via the is repr suffix; at the same time, is native is used for the routines that are actually implemented via native functions. These are the representations that can be used:

• CStruct corresponds to a struct in the C language. It is a composite data structure which includes different and heterogeneous lower-level data structures; see this for examples and further explanations.

• CPPStruct, similarly, correspond to a struct in C++. However, this is Rakudo specific for the time being.

• CPointer is a pointer in any of these languages. It is a dynamic data structure that must be instantiated before being used, can be used for classes whose methods are also native.

• CUnion is going to use the same representation as an union in C; see this for an example.

On the other hand, P6opaque is the default representation used for all objects in Raku.

class Thar {};
say Thar.REPR;    # OUTPUT: «P6opaque␤»

The metaobject protocol uses it by default for every object and class unless specified otherwise; for that reason, it is in general not necessary unless you are effectively working with that interface.

is on routines§

The is trait can be used on the definition of methods and routines to establish precedence and associativity. They act as a sub defined using trait_mod which take as argument the types and names of the traits that are going to be added. In the case of subroutines, traits would be a way of adding functionality which cuts across class and role hierarchies, or can even be used to add behaviors to independently defined routines.

is implementation-detail trait§

Available as of the 2020.05 release of the Rakudo compiler.

This trait is used by Raku language implementations and module authors to mark particular routines (including methods) as not meant to be a part of public API. While such routines can be found when looked up directly, they will not appear in results of introspection:

my &do-not-use-routine = CORE::<&DYNAMIC>;
say CORE::.keys.grep(* eq '&DYNAMIC'); # OUTPUT: «()␤»

Such routines are not meant for use by users and their behavior and availability can be changed anytime.

As of the 2021.02 release of the Rakudo compiler, it is also possible to apply the is implementation-detail method on classes and roles.

method is-implementation-detail§

method is-implementation-detail(--> True)

Applying this trait makes the is-implementation-detail method called on Code to return True, thus giving a hint to the user not to use it if they are not willing to maintain this code in case of changes for years to come:

my &fail-routine = &fail;
unless &fail-routine.is-implementation-detail {
    say "&fail is not an implementation detail, can expect backward compatibility";
}

sub PRIVATE-CALCULATION is implementation-detail { #`(Not safe to rely on this) }
if &PRIVATE-CALCULATION.is-implementation-detail {
    say "You better not to rely on &PRIVATE-CALCULATION unless you really know what you are doing";
}

method is-int§

method is-int(Range:D: --> Bool:D)

Returns True if both end points are Int values.

say ('a'..'d').is-int;                            # OUTPUT: «False␤»
say (1..^5).is-int;                               # OUTPUT: «True␤»
say (1.1..5.5).is-int;                            # OUTPUT: «False␤»

trait is§

multi trait_mod:<is>(Mu:U $child, Mu:U $parent)

The trait is accepts a type object to be added as a parent class of a class in its definition. To allow multiple inheritance the trait can be applied more than once. Adding parents to a class will import their methods into the target class. If the same method name occurs in multiple parents, the first added parent will win.

If no is trait is provided the default of Any will be used as a parent class. This forces all Raku objects to have the same set of basic methods to provide an interface for introspection and coercion to basic types.

class A {
    multi method from-a(){ 'A::from-a' }
}
say A.new.^parents(:all).raku;
# OUTPUT: «(Any, Mu)␤»

class B {
    method from-b(){ 'B::from-b ' }
    multi method from-a(){ 'B::from-A' }
}

class C is A is B {}
say C.new.from-a();
# OUTPUT: «A::from-a␤»

method is_mixin§

method is_mixin($obj)

Returns 1 If $obj has been marked as being a mixin with set_is_mixin, otherwise returns 0.

method is-absolute§

method is-absolute(Str:D $path --> Bool:D)

Returns True if the $path starts with a slash ("/") or backslash ("\"), even if they have combining character on them, optionally preceded by a volume:

say IO::Spec::Cygwin.is-absolute: "/foo";        # OUTPUT: «True␤»
say IO::Spec::Cygwin.is-absolute: "/\x[308]foo"; # OUTPUT: «True␤»
say IO::Spec::Cygwin.is-absolute: ｢C:\foo｣;      # OUTPUT: «True␤»
say IO::Spec::Cygwin.is-absolute: "bar";         # OUTPUT: «False␤»

method is_composed§

method is_composed($obj)

Returns 1 if the enum is composed, otherwise returns 0.