Operator::Util - A selection of array and hash functions that extend operators
This document describes Operator::Util version 0.05.
use Operator::Util qw( reduce reducewith zip zipwith cross crosswith hyper hyperwith applyop reverseop );
Warning: This is an early release of Operator::Util. Not all features described in this document are complete. Please see the "TODO" list for details.
A pragmatic approach at providing the functionality of many of Perl 6's meta-operators in Perl 5.
The terms "operator string" or "opstring" are used to describe a string that represents an operator, such as the string '+' for the addition operator or the string '.' for the concatenation operator. Opstrings default to binary infix operators and the short form may be used, e.g., '*' instead of 'infix:*'. All other operator types (prefix, postfix, circumfix, and postcircumfix) must have the type prepended in the opstrings, e.g., prefix:++ and postcircumfix:{}.
'+'
'.'
'*'
'infix:*'
prefix:++
postcircumfix:{}
When a list is passed as an argument for any of the functions, it must be either an array reference or a scalar value that will be used as a single-element list.
The following functions are provided but are not exported by default.
reducewith is an alias for reduce. It may be desirable to use reducewith to avoid naming conflicts or confusion with "reduce" in List::Util.
reducewith
reduce
Any infix opstring (except for non-associating operators) can be passed to reduce along with an arrayref to reduce the array using that operation:
reduce('+', [1, 2, 3]) # 1 + 2 + 3 = 6 my @a = (5, 6) reduce('*', \@a) # 5 * 6 = 30
reduce associates the same way as the operator used:
reduce('-', [4, 3, 2]) # 4-3-2 = (4-3)-2 = -1 reduce('**', [4, 3, 2]) # 4**3**2 = 4**(3**2) = 262144
For comparison operators (like <), all reduced pairs of operands are broken out into groups and joined with && because Perl 5 doesn't support comparison operator chaining:
<
&&
reduce('<', [1, 3, 5]) # 1 < 3 && 3 < 5
If fewer than two elements are given, the results will vary depending on the operator:
reduce('+', []) # 0 reduce('+', [5]) # 5 reduce('*', []) # 1 reduce('*', [5]) # 5
If there is one element, the reduce returns that one element. However, this default doesn't make sense for operators like < that don't return the same type as they take, so these kinds of operators overload the single-element case to return something more meaningful.
You can also reduce the comma operator, although there isn't much point in doing so. This just returns an arrayref that compares deeply to the arrayref passed in:
[1, 2, 3] reduce(',', [1, 2, 3]) # same thing
Operators with zero-element arrayrefs return the following values:
** # 1 (arguably nonsensical) =~ # 1 (also for 1 arg) !~ # 1 (also for 1 arg) * # 1 / # fail (reduce is nonsensical) % # fail (reduce is nonsensical) x # fail (reduce is nonsensical) + # 0 - # 0 . # '' << # fail (reduce is nonsensical) >> # fail (reduce is nonsensical) < # 1 (also for 1 arg) > # 1 (also for 1 arg) <= # 1 (also for 1 arg) >= # 1 (also for 1 arg) lt # 1 (also for 1 arg) le # 1 (also for 1 arg) gt # 1 (also for 1 arg) ge # 1 (also for 1 arg) == # 1 (also for 1 arg) != # 1 (also for 1 arg) eq # 1 (also for 1 arg) ne # 1 (also for 1 arg) ~~ # 1 (also for 1 arg) & # -1 (from ^0, the 2's complement in arbitrary precision) | # 0 ^ # 0 && # 1 || # 0 // # 0 = # undef (same for all assignment operators) , # []
You can say
reduce('||', [a(), b(), c(), d()])
to return the first true result, but the evaluation of the list is controlled by the semantics of the list, not the semantics of ||.
||
To generate all intermediate results along with the final result, you can set the triangle argument:
triangle
reduce('+', [1..5], triangle=>1) # (1, 3, 6, 10, 15)
The visual picture of a triangle is not accidental. To produce a triangular list of lists, you can use a "triangular comma":
reduce(',', [1..5], triangle=>1) # [1], # [1,2], # [1,2,3], # [1,2,3,4], # [1,2,3,4,5]
The zipwith function may be passed any infix opstring. It applies the operator across all groupings of its list elements.
zipwith
The string concatenating form is:
zipwith('.', ['a','b'], [1,2]) # ('a1', 'b2')
The list concatenating form when used like this:
zipwith(',', ['a','b'], [1,2], ['x','y'])
produces
('a', 1, 'x', 'b', 2, 'y')
This list form is common enough to have a shortcut, calling zip without an opstring as the first argument will use , by default:
zip
,
zip(['a','b'], [1,2], ['x','y'])
also produces
Any non-mutating infix operator may be used.
zipwith('*', [1,2], [3,4]) # (3, 8)
All assignment operators are considered mutating.
If the underlying operator is non-associating, so is zipwith, except for basic comparison operators since a chaining workaround is provided:
zipwith('cmp', \@a, \@b, \@c) # ILLEGAL zipwith('eq', \@a, \@b, \@c) # ok
The underlying operator is always applied with its own associativity, just as the corresponding reduce operator would do.
All lists are assumed to be flat; multidimensional lists are handled by treating the first dimension as the only dimension.
The response is a flat list by default. To return a list of arrayrefs, unset the flat argument:
flat
zip(['a','b'], [1,2], ['x','y'], flat=>0)
produces:
(['a', 1, 'x'], ['b', 2, 'y'])
The crosswith function may be passed any infix opstring. It applies the operator across all groupings of its list elements.
crosswith
crosswith('.', ['a','b'], [1,2]) # ('a1', 'a2', 'b1', 'b2')
crosswith(',', ['a','b'], [1,2], ['x','y'])
'a', 1, 'x', 'a', 1, 'y', 'a', 2, 'x', 'a', 2, 'y', 'b', 1, 'x', 'b', 1, 'y', 'b', 2, 'x', 'b', 2, 'y'
This list form is common enough to have a shortcut, calling cross without an opstring as the first argument will use , by default:
cross
cross(['a','b'], [1,2], ['x','y'])
crosswith('*', [1,2], [3,4]) # (3, 4, 6, 8)
If the underlying operator is non-associating, so is crosswith, except for basic comparison operators since a chaining workaround is provided:
crosswith('cmp', \@a, \@b, \@c) # ILLEGAL crosswith('eq', \@a, \@b, \@c) # ok
cross(['a','b'], [1,2], ['x','y'], flat=>0)
['a', 1, 'x'], ['a', 1, 'y'], ['a', 2, 'x'], ['a', 2, 'y'], ['b', 1, 'x'], ['b', 1, 'y'], ['b', 2, 'x'], ['b', 2, 'y']
hyperwith is an alias for hyper.
hyperwith
hyper
The hyper function operates on each element of its arrayref argument (or arguments) and returns a single list of the results. In other words, hyper distributes the operator over its elements as lists.
hyper('prefix:-' [1,2,3]) # (-1,-2,-3) hyper('+', [1,1,2,3,5], [1,2,3,5,8]) # (2,3,5,8,13)
Unary operators always produce a list of exactly the same shape as their single argument. When infix operators are presented with two arrays of identical shape, a result of that same shape is produced. Otherwise the result depends on what dwim arguments are passed.
dwim
For an infix operator, if either argument is insufficiently dimensioned, hyper "upgrades" it, but only if you tell it to "dwim" on that side.
hyper('-', [3,8,2,9,3,8], 1, dwim_right=>1) # (2,7,1,8,2,7) hyper('+=', \@array, 42, dwim_right=>1) # add 42 to each element
If you don't know whether one side or the other will be under-dimensioned, you can dwim on both sides:
hyper('*', $left, $right, dwim=>1)
The upgrade never happens on the non-dwim end of a hyper. If you write
hyper('*', $bigger, $smaller, dwim_left=>1) hyper('*', $smaller, $bigger, dwim_right=>1)
an exception is thrown, and if you write
hyper('*', $foo, $bar)
you are requiring the shapes to be identical, or an exception will be thrown.
For all hyper dwimminess, if a scalar is found where the other side expects an array, the scalar is considered to be an array of one element.
Once we have two lists to process, we have to decide how to put the elements into correspondence. If both sides are dwimmy, the short list will have to be repeated as many times as necessary to make the appropriate number of elements.
If only one side is dwimmy, then the list on that side only will be grown or truncated to fit the list on the non-dwimmy side.
This produces an array the same length as the corresponding dimension on the other side. The original operator is then recursively applied to each corresponding pair of elements, in case there are more dimensions to handle.
Here are some examples:
hyper('+', [1,2,3,4], [1,2] ) # always error hyper('+', [1,2,3,4], [1,2], dwim=>1 ) # (2,4,4,6) rhs dwims to 1,2,1,2 hyper('+', [1,2,3], [1,2], dwim=>1 ) # (2,4,4) rhs dwims to 1,2,1 hyper('+', [1,2,3,4], [1,2], dwim_left=>1 ) # (2,4) lhs dwims to 1,2 hyper('+', [1,2,3,4], [1,2], dwim_right=>1) # (2,4,4,6) rhs dwims to 1,2,1,2 hyper('+', [1,2,3], [1,2], dwim_right=>1) # (2,4,4) rhs dwims to 1,2,1 hyper('+', [1,2,3], 1, dwim_right=>1) # (2,3,4) rhs dwims to 1,1,1
Another way to look at it is that the dwimmy array's elements are indexed modulo its number of elements so as to produce as many or as few elements as necessary.
Note that each element of a dwimmy list may in turn be expanded into another dimension if necessary, so you can, for instance, add one to all the elements of a matrix regardless of its dimensionality:
hyper('+=', \@fancy, 1, dwim_right=>1)
On the non-dwimmy side, any scalar value will be treated as an array of one element, and for infix operators must be matched by an equivalent one-element array on the other side. That is, hyper is guaranteed to degenerate to the corresponding scalar operation when all its arguments are non-array arguments.
When using a unary operator no dwimmery is ever needed:
@negatives = hyper('prefix:-', \@positives) hyper('postfix:++', \@positions) # increment each hyper('->', \@objects, 'run', dwim_right=>1) # call ->run() on each hyper('length', ['f','oo','bar']) # (1, 2, 3)
Note that method calls are infix operators with a string used for the method name.
Hyper operators are defined recursively on nested arrays, so:
hyper('prefix:-', [[1, 2], 3]) # ([-1, -2], -3)
Likewise the dwimminess of dwimmy infixes propagates:
hyper('+', [[1, 2], 3], [4, [5, 6]], dwim=>1) # [[5, 6], [8, 9]]
hyper may be applied to hashes as well as to arrays. In this case "dwimminess" says whether to ignore keys that do not exist in the other hash, while "non-dwimminess" says to use all keys that are in either hash. That is,
hyper('+', \%foo, \%bar, dwim=>1)
gives you the intersection of the keys, while
hyper('+', \%foo, \%bar)
gives you the union of the keys. Asymmetrical hypers are also useful; for instance, if you say:
hyper('+', \%outer, \%inner, dwim_right=>1)
only the %inner keys that already exist in %outer will occur in the result. Note, however, that you want
hyper('+=', \%outer, \%inner)
in order to pass accumulated statistics up a tree, assuming you want %outer to have the union of keys.
Unary hash hypers and binary hypers that have only one hash operand will apply the hyper operator to just the values but return a new hash value with the same set of keys as the original hash.
hyper('prefix:-' {a => 1, b => 2, c => 3}) # (a => -1, b => -2, c => -3)
The optional named-argument flat can be passed to any of the above functions. It defaults to 1, which causes the function to return a flat list. When set to 0, it causes the return value from each operator to be stored in an array ref, resulting in a "list of lists" being returned from the function.
1
0
zip([1..3], ['a'..'c']) # 1, 'a', 2, 'b', 3, 'c' zip([1..3], ['a'..'c'], flat=>0) # [1, 'a'], [2, 'b'], [3, 'c']
Apply the operator OPSTRING to the operands OPERAND1 and OPERAND2. If an unary opstring is provided, only the first operand will be used.
applyop('.', 'foo', 'bar') # foobar applyop('prefix:++', 5) # 6
reverseop provides the same functionality as applyop except that OPERAND1 and OPERAND2 are reversed.
reverseop
applyop
reverseop('.', 'foo', 'bar') # barfoo
If an unary opstring is used, reverseop has the same functionality as applyop.
Allow more than two arrayrefs with zipwith, crosswith, and hyper
Support multi-dimensional binary operator distribution with hyper
Support the flat => 0 option
flat => 0
Add warnings on errors instead of simply returning
warn
return
Add named unary operators such as uc and lc
uc
lc
Support meta-operator literals such as Z and X in applyop
Z
X
Add evalop for evaling strings including meta-operator literals
evalop
eval
Should the first argument optionally be a subroutine ref instead of an operator string?
Should the flat => 0 option be changed to lol => 1?
lol => 1
perlop
"pairwise" in List::MoreUtils is similar to zip except that its first argument is a block instead of an operator string and the remaining arguments are arrays instead of array refs:
pairwise { $a + $b }, @array1, @array2 # List::MoreUtils zip '+', \@array1, \@array2 # Operator::Util
mesh a.k.a. "zip" in List::MoreUtils is similar to zip except that the arguments are arrays instead of array refs:
mesh
mesh @array1, @array2 # List::MoreUtils zip \@array1, \@array2 # Operator::Util
Set::CrossProduct is an object-oriented alternative to cross
The "Meta operators" section of Synopsis 3: Perl 6 Operators (http://perlcabal.org/syn/S03.html#Meta_operators) is the inspiration for this module
Nick Patch <patch@cpan.org>
This module is based on the Perl 6 specification, as described in the Synopsis and implemented in Rakudo
Much of the documentation is taken directly from Synopsis 3: Perl 6 Operators (http://perlcabal.org/syn/S03.html)
The tests were forked from the Official Perl 6 Test Suite (https://github.com/perl6/roast)
Copyright 2010, 2011 Nick Patch
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Operator::Util, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Operator::Util
CPAN shell
perl -MCPAN -e shell install Operator::Util
For more information on module installation, please visit the detailed CPAN module installation guide.