class Junction is Mu { }

A junction is an unordered composite value of zero or more values. Junctions autothread over many operations, which means that the operation is carried out for each junction element (also known as eigenstate), and the result is the junction of the return values of all those operators.

Junctions collapse into a single value in Boolean context, so when used in a conditional, a negation or an explicit coercion to Bool through the so or ? prefix operators. The semantics of this collapse depend on the junction type, which can be all, any, one or none.

As the table shows, in order to create junctions you use the command that represents the type of Junction followed by any object, or else call .all, .none or .one on the object.

say so 3 == (1..30).one;         # OUTPUT: «True␤» 
say so ("a" ^ "b" ^ "c") eq "a"; # OUTPUT: «True␤»

Junctions are very special objects. They fall outside the Any hierarchy, being only, as any other object, subclasses of Mu. That enables a feature for most methods: autothreading. Autothreading happens when a junction is bound to a parameter of a code object that doesn't accept values of type Junction. Instead of producing an error, the signature binding is repeated for each value of the junction.

Example:

my $j = 1|2;
if 3 == $j + 1 {
    say 'yes';
}

First autothreads over the infix:<+> operator, producing the Junction 2|3. The next autothreading step is over infix:<==> , which produces False|True. The if conditional evaluates the junction in Boolean context, which collapses it to True. So the code prints yes\n.

The type of a Junction does not affect the number of items in the resultant Junction after autothreading. For example, using a one Junction during Hash key lookup, still results in a Junction with several items. It is only in Boolean context would the type of the Junction come into play:

my %h = :42foo, :70bar;
say    %h{one <foo meow>}:exists; # OUTPUT: «one(True, False)␤» 
say so %h{one <foo meow>}:exists; # OUTPUT: «True␤» 
say    %h{one <foo  bar>}:exists; # OUTPUT: «one(True, True)␤» 
say so %h{one <foo  bar>}:exists; # OUTPUT: «False␤»

Note that the compiler is allowed, but not required, to parallelize autothreading (and Junction behavior in general), so it is usually an error to autothread junctions over code with side effects.

Autothreading implies that the function that's autothreaded will also return a Junction of the values that it would usually return.

(1..3).head( 2|3 ).say; # OUTPUT: «any((1 2), (1 2 3))␤»

Since .head returns a list, the autothreaded version returns a Junction of lists.

(1..3).contains( 2&3 ).say; # OUTPUT: «all(True, True)␤»

Likewise, .contains returns a Boolean; thus, the autothreaded version returns a Junction of Booleans. In general, all methods and routines that take an argument of type T and return type TT, will also accept junctions of T, returning junctions of TT.

Implementations are allowed to short-circuit Junctions. For example one or more routine calls (a(), b(), or c()) in the code below might not get executed at all, if the result of the conditional has been fully determined from routine calls already performed (only one truthy return value is enough to know the entire Junction is true):

if a() | b() | c() {
    say "At least one of the routines was called and returned a truthy value"
}

Junctions are meant to be used as matchers in a Boolean context; introspection of junctions is not supported. If you feel the urge to introspect a junction, use a Set or a related type instead.

Usage examples:

my @list = <1 2 "Great">;
@list.append(True).append(False);
my @bool_or_int = grep Bool|Int, @list;
 
sub is_prime(Int $x) returns Bool {
    # 'so' is for Boolean context 
    so $x %% none(2..$x.sqrt);
}
my @primes_ending_in_1 = grep &is_prime & / 1$ /, 2..100;
say @primes_ending_in_1;        # OUTPUT: «[11 31 41 61 71]␤» 
 
my @exclude = <~ .git>;
for dir(".") { say .Str if .Str.ends-with(none @exclude) }

Special care should be taken when using all with arguments that may produce an empty list:

my @a = ();
say so all(@a) # True, because there are 0 Falses

To express "all, but at least one", you can use @a && all(@a)

my @a = ();
say so @a && all(@a);   # OUTPUT: «False␤»

Negated operators are special-cased when it comes to autothreading. $a !op $b is rewritten internally as !($a op $b). The outer negation collapses any junctions, so the return value always a plain Bool.

my $word = 'yes';
my @negations = <no none never>;
if $word !eq any @negations {
    say '"yes" is not a negation';
}

Note that without this special-casing, an expression like $word ne any @words would always evaluate to True for non-trivial lists on one side.

For this purpose, infix:<ne> counts as a negation of infix:<eq> .

In general it is more readable to use a positive comparison operator and a negated junction:

my $word = 'yes';
my @negations = <no none never>;
if $word eq none @negations {
    say '"yes" is not a negation';
}

Failures and exceptions §

Failures are just values like any other, as far as Junctions are concerned:

my $j = +any "not a number", "42", "2.1";
my @list = gather for $j -> $e {
    take $e if $e.defined;
}
@list.say; # OUTPUT: «[42 2.1]␤»

Above, we've used prefix + operator on a Junction to coerce the strings inside of it to Numeric. Since the operator returns a Failure when a Str that doesn't contain a number gets coerced to Numeric, one of the elements in the Junction is a Failure. Failures do not turn into exceptions until they are used or sunk, but we can check for definedness to avoid that. That is what we do in the loop that runs over the elements of the junction, adding them to a list only if they are defined.

The exception will be thrown, if you try to use the Failure as a value—just like as if this Failure were on its own and not part of the Junction:

my $j = +any "not a number", "42", "2.1";
try say $j == 42;
$! and say "Got exception: $!.^name()";
# OUTPUT: «Got exception: X::Str::Numeric␤» 

Note that if an exception gets thrown when any of the values in a Junction get computed, it will be thrown just as if the problematic value were computed on its own and not with a Junction; you can't just compute the values that work while ignoring exceptions:

sub calc ($_) { die when 13 }
my $j = any 1..42;
say try calc $j; # OUTPUT: «Nil␤»

Only one value above causes an exception, but the result of the try block is still a Nil. A possible way around it is to cheat and evaluate the values of the Junction individually and then re-create the Junction from the result:

sub calc ($_) { die when 13 }
my $j = any 1..42;
$j = any (gather $j».take).grep: {Nil !=== try calc $_};
say so $j == 42; # OUTPUT: «True␤»

Smartmatching §

Note that using Junctions on the right-hand side of ~~ works slightly differently than using Junctions with other operators.

Consider this example:

say 25 == (25 | 42);    # OUTPUT: «any(True, False)␤» – Junction 
say 25 ~~ (25 | 42);    # OUTPUT: «True␤»             – Bool

The reason is that == (and most other operators) are subject to auto-threading, and therefore you will get a Junction as a result. On the other hand, ~~ will call .ACCEPTS on the right-hand-side (in this case on a Junction) and the result will be a Bool.

Methods §

method new §

Defined as:

multi method new(Junction: \values, Str :$type!)
multi method new(Junction: Str:D \type, \values)

These constructors build a new junction from the type that defines it and a set of values.

my $j = Junction.new(<Þor Oðinn Loki>, type => "all");
my $n = Junction.new( "one", 1..6 )

The main difference between the two multis is how the type of the Junction is passed as an argument; either positionally as the first argument, or as a named argument using type.

method defined §

Defined as:

multi method defined(Junction:D:)

Checks for definedness instead of Boolean values.

say ( 3 | Str).defined ;   # OUTPUT: «True␤» 
say (one 3, Str).defined;  # OUTPUT: «True␤» 
say (none 3, Str).defined; # OUTPUT: «False␤»

Failures are also considered non-defined:

my $foo=Failure.new;
say (one 3, $foo).defined; # OUTPUT: «True␤»

Since 6.d, this method will autothread.

method Bool §

Defined as:

multi method Bool(Junction:D:)

Collapses the Junction and returns a single Boolean value according to the type and the values it holds. Every element is transformed to Bool.

my $n = Junction.new( "one", 1..6 );
say $n.Bool;                         # OUTPUT: «False␤» 

All elements in this case are converted to True, so it's false to assert that only one of them is.

my $n = Junction.new( "one", <0 1> );
say $n.Bool;                         # OUTPUT: «True␤» 

Just one of them is truish in this case, 1, so the coercion to Bool returns True.

method Str §

Defined as:

multi method Str(Junction:D:)

Autothreads the .Str method over its elements and returns results as a Junction. Output methods that use .Str method (print and put) are special-cased to autothread junctions, despite being able to accept a Mu type.

method iterator §

Defined as:

multi method iterator(Junction:D:)

Returns an iterator over the Junction converted to a List.

method gist §

Defined as:

multi method gist(Junction:D:)

Collapses the Junction and returns a Str composed of the type of the junction and the gists of its components:

<a 42 c>.all.say; # OUTPUT: «all(a, 42, c)␤»

method raku §

Defined as:

multi method raku(Junction:D:)

Collapses the Junction and returns a Str composed of raku of its components that evaluates to the equivalent Junction with equivalent components:

<a 42 c>.all.raku.put; # OUTPUT: «all("a", IntStr.new(42, "42"), "c")␤»

infix ~ §

Defined as:

multi sub infix:<~>(Str:D $a, Junction:D $b)
multi sub infix:<~>(Junction:D $a, Str:D $b)
multi sub infix:<~>(Junction:D \a, Junction:D \b)

The infix ~ concatenation can be used to merge junctions into a single one or merge Junctions with strings. The resulting junction will have all elements merged as if they were joined into a nested loop:

my $odd  = 1|3|5;
my $even = 2|4|6;
 
my $merged = $odd ~ $even;
say $merged; # OUTPUT: «any(12, 14, 16, 32, 34, 36, 52, 54, 56)␤» 
 
say "Found 34!" if 34 == $merged; # OUTPUT: «Found 34!␤» 
my $prefixed = "0" ~ $odd;
say "Found 03" if "03" == $prefixed; # OUTPUT: «Found 03!␤» 
 
my $postfixed = $odd ~ "1";
say "Found 11" if 11 == $postfixed; # OUTPUT: «Found 11!␤» 

On the other hand, the versions of ~ that use a string as one argument will just concatenate the string to every member of the Junction, creating another Junction with the same number of elements.

See Also §

Type Graph §