TITLE

Synopsis 3: Perl 6 Operators

AUTHOR

Luke Palmer <luke@luqui.org>

VERSION

  Maintainer: Larry Wall <larry@wall.org>
  Date: 8 Mar 2004
  Last Modified: 2 Apr 2008
  Number: 3
  Version: 135

Overview

For a summary of the changes from Perl 5, see "Changes to Perl 5 operators".

Operator precedence

From t/operators/precedence/builtins.t lines 12–186 (46 √, 2 ×): (skip)

Not counting terms and terminators, Perl 6 has 23 operator precedence levels (same as Perl 5, but differently arranged). Here we list the levels from "tightest" to "loosest", along with a few examples of each level:

    A  Level             Examples
    =  =====             ========
    N  Terms             42 3.14 "eek" qq["foo"] $x :!verbose @$array
    L  Method postfix    .meth .+ .? .* .() .[] .{} .<> .«» .:: .= .^ .:
    L  Autoincrement     ++ --
    R  Exponentiation    **
    L  Symbolic unary    ! + - ~ ? | +^ ~^ ?^ \ ^ =
    L  Multiplicative    * / % +& +< +> ~& ~< ~> ?& div mod
    L  Additive          + - +| +^ ~| ~^ ?| ?^
    N  Replication       x xx
    L  Concatenation     ~
    X  Junctive and      &
    X  Junctive or       | ^
    L  Named unary       sleep abs sin
    N  Nonchaining infix but does <=> leg cmp .. ..^ ^.. ^..^
    C  Chaining infix    != == < <= > >= eq ne lt le gt ge ~~ === eqv !eqv
    L  Tight and         &&
    L  Tight or          || ^^ // min max
    L  Conditional       ?? !! ff fff
    R  Item assignment   = := ::= => += -= **= xx= .=
    L  Loose unary       true not
    X  Comma operator    , p5=>
    X  List infix        Z minmax X X~X X*X XeqvX
    R  List prefix       : print push say die map substr ... [+] [*] any $ @
    L  Loose and         and andthen
    L  Loose or          or xor orelse
    N  Terminator        ; <==, ==>, <<==, ==>>, {...}, unless, extra ), ], }

The associativities specified above are:

        Assoc     Meaning of $a op $b op $c
        =====     =========================
    L   left      ($a op $b) op $c
    R   right     $a op ($b op $c)
    N   non       ILLEGAL
    C   chain     ($a op $b) and ($b op $c)
    X   list      op($a, $b, $c) or op($a; $b; $c)

Note that list associativity only works between identical operators. If two different list-associative operators have the same precedence, they are assumed to be left-associative with respect to each other. For example, the X cross operator and the Z zip operator both have a precedence of "list infix", but:

    @a X @b Z @c

is parsed as:

    (@a X @b) Z @c

If you don't see your favorite operator above, the following sections cover all the operators in precedence order. Basic operator descriptions are here; special topics are covered afterwards.

Term precedence

This isn't really a precedence level, but it's in here because no operator can have tighter precedence than a term. See S02 for longer descriptions of various terms. Here are some examples.

• Int literal

      42

• Num literal

      3.14

• Non-interpolating Str literal

      '$100'

• Interpolating Str literal

      "Answer = $answer\n"

• Generalized Str literal

      q["$100"]
      qq["$answer"]

• Heredoc

      qq:to/END/
          Dear $recipient:
          Thanks!
          Sincerely,
          $me
          END

• Array composer

      [1,2,3]

  Provides list context inside. (Technically, it really provides a "semilist" context, which is a semicolon-separated list of statements, each of which is interpreted in list context and then concatenated into the final list.)

• Hash composer

      { }
      { a => 42 }

  Inside must be either empty, or a single list starting with a pair or a hash, otherwise you must use hash() or %() instead.

• Closure

      { ... }

  When found where a statement is expected, executes immediately. Othewise always defers evaluation of the inside scope.

• Capture composer

      \(@a,$b,%c)

  An abstraction representing an argument list that doesn't yet know its context.

• Sigiled variables

      $x
      @y
      %z
      $^a
      $?FILE
      @@slice
      &func
      &div:(Int, Int --> Int)

• Sigils as contextualizer functions

      $()
      @()
      %()
      &()
      @@()

• Regexes in quote-like notation

      /abc/
      rx:i[abc]
      s/foo/bar/

• Transliterations

      tr/a..z/A..Z/;

  Note ranges use .. rather than -.

• Type names

      Num
      ::Some::Package

• Subexpressions circumfixed by parentheses

      (1+2)

  Parentheses are parsed on the inside as a semicolon-separated list of statements, which (unlike the statements in a block) returns the results of all the statements concatenated together as a List of Capture. How that is subsequently treated depends on its eventual binding.

• Function call with parens:

      a(1)

• Pair composers

      :by(2)
      :!verbose

• Signature literal

      :(Dog $self:)

• Method call with implicit invocant

      .meth       # call on $_
      .=meth      # modify $_

  Note that this may occur only where a term is expected. Where a postfix is expected, it is a postfix. If only an infix is expected (that is, after a term with intervening whitespace), .meth is a syntax error. (The .=meth form is allowed there only because there is a special .= infix assignment operator that is equivalent in semantics to the method call form but that allows whitespace between the = and the method name.)

• Listop (leftward)

      4,3, sort 2,1       # 4,3,1,2

  As in Perl 5, a list operator looks like a term to the expression on its left, so it binds tighter than comma on the left but looser than comma on the right--see List prefix precedence below.

• 0-ary functions

      self
      undef
      rand

Method postfix precedence

All method postfixes start with a dot, though the dot is optional for subscripts. Since these are the tightest standard operator, you can often think of a series of method calls as a single term that merely expresses a complicated name.

See S12 for more discussion of single dispatch method calls.

• Standard single-dispatch method calls

      $obj.meth

• Variants of standard single-dispatch method call

      $obj.+meth
      $obj.?meth
      $obj.*meth

  In addition to the ordinary . method invocation, there are variants .*, .?, and .+ to control how multiple related methods of the same name are handled.

• Class-qualified method call

      $obj.::Class::meth
      $obj.Class::meth    # same thing, assuming Class is predeclared

  As in Perl 5, tells the dispatcher which class to start searching from, not the exact method to call.

• Mutating method call

      $obj.=meth

  The .= operator does inplace modification of the object on the left.

• Meta-method call

      $obj.^meth

  The .^ operator calls a class metamethod; foo.^bar is short for foo.HOW.bar.

• Method-like postcircumfixes

      $routine.()
      $array.[]
      $hash.{}
      $hash.<>
      $hash.«»

  The dotless forms of these have exactly the same precedences.

• Dotted form of any other postfix operator

      $x.++         # postfix:<++>($x)

• Dotted postfix form of any other prefix operator

      $x.:<++>       # prefix:<++>($x)

• There is specifically no infix:<.> operator, so

      $foo . $bar

  will always result in a compile-time error indicating the user should use infix:<~> instead. This is to catch an error likely to be made by Perl 5 programmers learning Perl 6.

Autoincrement precedence

From t/spec/S03-operators/autoincrement.t lines 9–51 (30 √, 0 ×): (skip)

From t/operators/auto.t lines 9–98 (38 √, 5 ×): (skip)

From t/operators/inc.t lines 7–142 (39 √, 0 ×): (skip)

As in C, these operators increment or decrement the object in question either before or after the value is taken from the object, depending on whether it is put before or after. Also as in C, multiple references to a single mutating object in the same expression may result in undefined behavior unless some explicit sequencing operator is interposed. See "Sequence points".

As with all postfix operators in Perl 6, no space is allowed between a term and its postfix. See S02 for why, and for how to work around the restriction with an "unspace".

As mutating methods, all these operators dispatch to the type of the operand and return a result of the same type, but they are legal on value types only if the (immutable) value is stored in a mutable container. However, a bare undefined value (in a suitable Scalar container) is allowed to mutate itself into an Int in order to support the common idiom:

    say $x unless %seen{$x}++;

Increment of a Str (in a suitable container) works similarly to Perl 5, but is generalized slightly. A scan is made for the final alphanumeric sequence in the string that is not preceded by a '.' character. Unlike in Perl 5, this alphanumeric sequence need not be anchored to the beginning of the string, nor does it need to begin with an alphabetic character; the final sequence in the string matching <!after '.'> <rangechar>+ is incremented regardless of what comes before it.

From t/spec/S03-operators/autoincrement.t lines 52–111 (8 √, 4 ×): (skip)

The <rangechar> character class is defined as that subset of \w that Perl knows how to increment within a range, as defined below.

The additional matching behaviors provide two useful benefits: for its typical use of incrementing a filename, you don't have to worry about the path name or the extension:

    $file = "/tmp/pix000.jpg";
    $file++;            # /tmp/pix001.jpg, not /tmp/pix000.jph

Perhaps more to the point, if you happen to increment a string that ends with a decimal number, it's likely to do the right thing:

    $num = "123.456";
    $num++;             # 124.456, not 123.457

Character positions are incremented within their natural range for any Unicode range that is deemed to represent the digits 0..9 or that is deemed to be a complete cyclical alphabet for (one case of) a (Unicode) script. Only scripts that represent their alphabet in codepoints that form a cycle independent of other alphabets may be so used. (This specification defers to the users of such a script for determining the proper cycle of letters.) We arbitrarily define the ASCII alphabet not to intersect with other scripts that make use of characters in that range, but alphabets that intersperse ASCII letters are not allowed.

If the current character in a string position is the final character in such a range, it wraps to the first character of the range and sends a "carry" to the position left of it, and that position is then incremented in its own range. If and only if the leftmost position is exhausted in its range, an additional character of the same range is inserted to hold the carry in the same fashion as Perl 5, so incrementing '(zz99)' turns into '(aaa00)' and incrementing '(99zz)' turns into '(100aa)'.

The following Unicode ranges are some of the possible rangechar ranges. For alphabets we might have ranges like:

    A..Z        # ASCII uc
    a..z        # ASCII lc
    Α..Ω        # Greek uc
    α..ω        # Greek lc (presumably skipping U+03C2, final sigma)
    א..ת        # Hebrew
      etc.      # (XXX out of my depth here)

For digits we have ranges like:

    0..9        # ASCII
    ٠..٩        # Arabic-Indic
    ०..९        # Devangari
    ০..৯        # Bengali 
    ੦..੯        # Gurmukhi
    ૦..૯        # Gujarati
    ୦..୯        # Oriya
      etc.

Other non-script 0..9 ranges may also be incremented, such as

    ⁰..⁹        # superscripts (note, cycle includes latin-1 chars)
    ₀..₉        # subscripts
    ０..９      # fullwith digits

Conjecturally, any common sequence may be treated as a cycle even if it does not represent 0..9:

    Ⅰ..Ⅻ        # clock roman numerals uc
    ⅰ..ⅻ        # clock roman numerals lc
    ①..⑳        # circled digits 1..20
    ⒜..⒵        # parenthesize lc
    ⚀..⚅        # die faces 1..6
    ❶..❿        # dingbat negative circled 1..10
      etc.

While it doesn't really make sense to "carry" such numbers when they reach the end of their cycle, treating such values as incrementable may be convenient for writing outlines and similar numbered bullet items. (Note that we can't just increment unrecognized characters, because we have to locate the string's final sequence of rangechars before knowing which portion of the string to increment. Note also that all character increments can be handled by lookup in a single table of successors since we've defined our ranges not to include overlapping cycles.)

Perl 6 also supports Str decrement with similar semantics, simply by running the cycles the other direction. However, leftmost characters are never removed, and the decrement fails when you reach a string like "aaa" or "000".

Increment and decrement on non-<Str> types are defined in terms of the .succ and .pred methods on the type of object in the Scalar container. More specifically,

    ++$var
    --$var

are equivalent to

    $var.=succ
    $var.=pred

If the type does not support these methods, the corresponding increment or decrement operation will fail. (The optimizer is allowed to assume that the ordinary increment and decrement operations on integers will not be overridden.)

Increment of a Bool (in a suitable container) turns it true. Decrement turns it false regardless of how many times it was previously incremented. This is useful if your %seen array is actually a KeySet, in which case decrement actually deletes it from the KeySet.

• Autoincrement prefix:<++> or postfix:<++> operator

      $x++
      ++$x;

• Autodecrement prefix:<--> or postfix:<--> operator

      $x--
      --$x

Exponentiation precedence

• infix:<**> exponentiation operator

      $x ** 2

  If the right argument is not a non-negative integer, the result is likely to be an approximation. If the right argument is of an integer type, exponentiation is at least as accurate as repeated multiplication on the left side's type. (From which it can be deduced that Int**UInt is always exact, since Int supports arbitrary precision.) If the right argument is an integer represented in a non-integer type, the accuracy is left to implementation provided by that type; there is no requirement to recognize an integer to give it special treatment.

Symbolic unary precedence

• prefix:<?>, boolean context

      ?$x

  Evaluates the expression as a boolean and returns True if expression is true or False otherwise. See "true" below for a low-precedence alternative.

• prefix:<!>, boolean negation

      !$x

  Returns the opposite of what ? would. See "not" below for a low-precedence alternative.

• prefix:<+>, numeric context

      +$x

  Unlike in Perl 5, where + is a no-op, this operator coerces to numeric context in Perl 6. (It coerces only the value, not the original variable.) For values that are not already considered numeric, the narrowest appropriate type of Int, Num, or Complex will be returned; however, string containing two integers separated by a / will be returned as a Rat. Exponential notation and radix notations are recognized.

• prefix:<->, numeric negation

      -$x

  Coerces to numeric and returns the arithmetic negation of the resulting number.

• prefix:<~>, string context

      ~$x

  Coerces the value to a string. (It only coerces the value, not the original variable.)

• prefix:<|>, flatten object into arglist

      | $capture

  Interpolates the contents of the Capture (or Capture-like) value into the current argument list as if they had been specified literally.

• prefix:<+^>, numeric bitwise negation

      +^$x

  Coerces to integer and then does bitwise negation (complement) on the number.

• prefix:<~^>, string bitwise negation

      ~^$x
  Coerces to string buffer and then does bitwise negation (complement)
  on each element.

• prefix:<?^>, boolean bitwise negation

      ?^$x

  Coerces to boolean and then flips the bit. (Same as !.)

• prefix:<\>, Capture constructor

      \$x
      \@x
      \%x
      \($invocant: $pos1, $pos2, :named($arg))

  Defers the contextualization of its argument or arguments till it is bound into some other context.

• prefix:<^>, upto operator

      ^$limit

  Constructs a range of 0..^$limit or locates a metaclass as a shortcut for $limit.HOW. See "Range semantics".

• prefix:<=>, iterate iterator

      =$iterator

  Unary = reads lines from a filehandle or filename, or iterates an iterator, or in general causes a scalar to explode its guts when it would otherwise not. How it does that is context sensitive. For instance, =$iterator is item/list context sensitive and will produce one value in item context but many values in list context. The production of values is abstract here, so a lazy list merely remembers that it should iterate the iterator to completion upon demand. Use an eager list to force completion.

  Use @$iterator to produce a list of all the values even in item context, and $$iterator to produce a single value even in list context. On the other hand, =$capture produces all parts of the capture that makes sense in the current list context, depending on what controls that list context. [Conjecture: the previous sentence is non-sensical.]

Multiplicative precedence

• infix:<*>

      $x*$y

  Multiplication, resulting in wider type of the two.

• infix:</>

      $numerator / $denominator

  If either operand is of Num type, converts both operands to Num and does division returning Num. If the denominator is zero, returns an object representing either +Inf, NaN, or -Inf as the numerator is positive, zero, or negative. (This is construed as the best default in light of the operator's possible use within hyperoperators and junctions. Note however that these are not actually the native IEEE non-numbers; they are undefined values of the "unthrown exception" type that happen to represent the corresponding IEEE concepts, and if you subsequently try to use one of these values in a non-parallel computation, it will likely throw an exception at that point.)

  If both operands are of integer type, you still get a Num, but the Num type is allowed to do the division lazily; internally it may store a Rat until the time a value is called for. If converted to Rat directly no division ever need be done.

• infix:<div>, generic division

      $numerator div $denominator

  Dispatches to the infix:<div> multi most appropriate to the operand types. Policy on what to do about division by zero is up to the type, but for the sake of hyperoperators and junctions those types that can represent overflow (or that can contain an unthrown exception) should try to do so rather than simply throwing an exception. (And in general, other operators that might fail should also consider their use in hyperops and junctions, and whether they can profitably benefit from a lazy exception model.)

  Use of div on two Int values results in a ratio of the Rat type.

• infix:<%>, modulus

      $x % $mod

  Always floor semantics using Num or Int.

• infix:<mod>, generic modulus

      $x mod $mod

  Dispatches to the infix:<mod> multi most appropriate to the operand types.

• infix:{'+&'}, numeric bitwise and

      $x +& $y

  Converts both arguments to integer and does a bitwise numeric AND.

• infix:{'+<'}, numeric shift left

      $integer +< $bits

• infix:{'+>'}, numeric shift right

      $integer +> $bits

  By default, signed types do sign extension, while unsigned types do not, but this may be enabled or disabled with a :signed or :!signed adverb.

• infix:<~&>, buffer bitwise and

      $x ~& $y

• infix:{'~<'}, buffer bitwise shift left

      $buf ~< $bits

• infix:{'~>'}, buffer bitwise shift right

      $buf ~> $bits

  Sign extension is not done by default but may be enabled with a :signed adverb.

• infix:<?&>, boolean bitwise and

      $x ?& $y

Any bit shift operator may be turned into a rotate operator with the :rotate adverb. If :rotate is specified, the concept of sign extension is meaningless, and you may not specify a :signed adverb.

Additive precedence

• infix:<+>, numeric addition

      $x + $y

  Microeditorial: As with most of these operators, any coercion or type mismatch is actually handled by multiple dispatch. The intent is that all such variants preserve the notion of numeric addition to produce a numeric result, presumably stored in suitably "large" numeric type to hold the result. Do not overload the + operator for other purposes, such as concatenation. (And please do not overload the bitshift operators to do I/O.) In general we feel it is much better for you to make up a different operator than overload an existing operator for "off topic" uses. All of Unicode is available for this purpose.

• infix:<->, numeric subtraction

      $x - $y

• infix:<+|>, numeric bitwise inclusive or

      $x +| $y

• infix:<+^> numeric bitwise exclusive or

      $x +^ $y

• infix:<~|>, buffer bitwise inclusive or

      $x ~| $y

• infix:<~^> buffer bitwise exclusive or

      $x ~^ $y

• infix:<?|>, boolean bitwise inclusive or

      $x ?| $y

• infix:<?^> boolean bitwise exclusive or

      $x ?^ $y

Replication

• infix:<x>, string/buffer replication

      $string x $count

  Evaluates the left argument in string context, replicates the resulting string value the number of times specified by the right argument and returns the result as a single concatenated string regardless of context.

  If the count is less than 1, returns the null string. The count may not be * because Perl 6 does not support infinite strings. (At least, not yet...) Note, however, that an infinite string may be emulated with cat($string xx *).

• infix:<xx>, list replication

      @list xx $count

  Evaluates the left argument in list context, replicates the resulting Capture value the number of times specified by the right argument and returns the result in a context dependent fashion. If the operator is being evaluated in ordinary list context, the operator returns a flattened list. In slice (@@) context, the operator converts each Capture to a separate sublist and returns the list of those sublists.

  If the count is less than 1, returns the empty list, (). If the count is *, returns an infinite list (lazily, since lists are lazy by default).

Concatenation

From t/operators/operator.t lines 17–19 (1 √, 0 ×): (skip)

From t/operators/operator.t lines 49–53 (1 √, 0 ×): (skip)

• infix:<~>, string/buffer concatenation

      $x ~ $y

Junctive and (all) precedence

• infix:<&>, all() operator

      $x & $y

Junctive or (any) precedence

• infix:<|>, any() operator

      $x | $y

• infix:<^>, one() operator

      $x ^ $y

Named unary precedence

Functions of one argument

    int
    sleep
    abs
    sin
    ...         # see S29 Functions

Note that, unlike in Perl 5, you must use the .meth forms to default to $_ in Perl 6.

There is no unary rand function in Perl 6, though there is a .rand method call and a 0-ary rand term.

• prefix:<int>

  Coerces to type Int. Floor semantics are used for fractional values, including strings that appear to express fractional values. That is, int($x) must have the same result as int(+$x) in all cases. All implicit conversions to integer use the same semantics.

  (Note that, despite the fact that int is a valid native type name, this function does not express conversion to that native type. Such subtype conversions are done automatically upon assignment to a subtyped container, and fail if the container cannot hold the value.)

• prefix:<sleep>

  Suspends the current thread of execution for the specified number of seconds, which may be fractional.

• prefix:<abs>

  Returns the absolute value of the specified argument.

Nonchaining binary precedence

• infix:<but>

      $value but Mixin

• infix:<does>

      $object does Mixin

• Sort comparisons

      $num1 <=> $num2
      $str1 leg $str2
      $obj1 cmp $obj2

  These operators compare their operands using numeric, string, or eqv semantics respectively, and depending on the order return one of Order::Increase, Order::Same, or Order::Decrease (which numerify to -1, 0, or +1). See "Comparison semantics".

• Range object constructor

      $min .. $max
      $min ^.. $max
      $min ..^ $max
      $min ^..^ $max

  Constructs Range objects, optionally excluding one or both endpoints. See "Range semantics".

Chaining binary precedence

From t/spec/S03-operators/equality.t lines 10–41 (15 √, 0 ×): (skip)

From t/spec/S03-operators/relational.t lines 9–49 (20 √, 0 ×): (skip)

All operators on this precedence level may be chained; see "Chained comparisons".

• infix:<==> etc.

  From t/operators/operator.t lines 26–48 (13 √, 0 ×): (skip)

  	# L<S03/Chaining binary precedence/==>
  	my $five = 5;
  	my $four = 4;
  	my $wibble = 4;
  √	ok(!($five == $four), "== (false)");
  √	ok($wibble == $four, "== (true)");
  √	ok(!($wibble != $four), "== (false)");
  √	ok($five != $four, "!= (true)");
  √	ok($five == 5, "== (const on rhs)");
  √	ok(!($five != 5), "!= (const on rhs)");
  √	ok(5 == $five, "== (const on lhs)");
  √	ok(!(5 != $five), "!= (const on lhs)");
  √	ok($five == (2 + 3), "== (sum on rhs)");
  √	ok(!($five != (2 + 3)), "== (sum on rhs)");
  √	is(2 + 3, $five, "== (sum on lhs)");
  √	ok((2 + 3) == 5, "== (sum on lhs)");
  √	ok(!((2 + 3) != $five), "== (sum on lhs)");

   

      == != < <= > >=

  As in Perl 5, converts to Num before comparison. != is short for !==.

• infix:<eq> etc.

      eq ne lt le gt ge

  As in Perl 5, converts to Str before comparison. ne is short for !eq.

• Generic ordering

      $a before $b
      $a after $b

• Smart match

      $obj ~~ $pattern

  Perl 5's =~ becomes the "smart match" operator ~~, with an extended set of semantics. See "Smart matching" for details.

  To catch "brainos", the Perl 6 parser defines an infix:<=~> operator which always fails at compile time with a message directing the user to use ~~ or ~= (string append) instead if they meant it as a single operator, or to put a space between if they really wanted to assign a stringified value as two separate operators.

  From t/operators/brainos.t lines 15–24 (no results): (skip)

  	#L<S03/Chaining binary precedence/"To catch">
  	my $str = 'foo';
  	eval q{$str =~ m/bar/;};
  	if $!.defined {
  	pass "caught =~ braino, saying $!";
  	}
  	else {
  	flunk "didn't catch =~ braino";
  	}

   

  A negated smart match is spelled !~~.

  From t/operators/negated_smartmatch.t lines 7–10 (1 √, 0 ×): (skip)

  	#L<S03/Chaining binary precedence/"A negated smart match is spelled">
  	my $opposites = (not(0 ~~ rx:Perl5/0/) xor not(0 !~~ rx:Perl5/0/));
  √	ok($opposites, "~~ and !~~ are opposites");

   
• Container identity

      VAR($a) =:= VAR($b)

  See "Comparison semantics".

• Value identity

  From t/operators/value_equivalence.t lines 7–131 (39 √, 3 ×): (skip)

  <

  	L<S03/"Chaining binary precedence" /Value identity>
  	C<===> and C<eqv> are 2 distinct operators, where C<===> tests value
  	equivalence for immutable types and reference equivalence for
  	mutable types, and C<eqv> tests value equivalence for snapshots of mutable
  	types.  So C<(1,2) === (1,2)> returns true but C<[1,2] === [1,2]> returns
  	false, and C<[1,2] eqv [1,2]> returns true.
  	=cut