1NiceSlice(3) User Contributed Perl Documentation NiceSlice(3)
2
6 PDL::NiceSlice - toward a nicer slicing syntax for PDL
7
9 use PDL::NiceSlice;
10 $x(1:4) .= 2; # concise syntax for ranges
12 print $y((0),1:$end); # use variables in the slice expression
13 $x->xchg(0,1)->(($pos-1)) .= 0; # default method syntax
14 $idx = long 1, 7, 3, 0; # a piddle of indices
16 $x(-3:2:2,$idx) += 3; # mix explicit indexing and ranges
17 $x->clump(1,2)->(0:30); # 'default method' syntax
18 $x(myfunc(0,$var),1:4)++; # when using functions in slice expressions
19 # use parentheses around args!
20 $y = $x(*3); # Add dummy dimension of order 3
22 # modifiers are specified in a ;-separated trailing block
24 $x($x!=3;?)++; # short for $x->where($x!=3)++
25 $x(0:1114;_) .= 0; # short for $x->flat->(0:1114)
26 $y = $x(0:-1:3;|); # short for $x(0:-1:3)->sever
27 $n = sequence 3,1,4,1;
28 $y = $n(;-); # drop all dimensions of size 1 (AKA squeeze)
29 $y = $n(0,0;-|); # squeeze *and* sever
30 $c = $x(0,3,0;-); # more compact way of saying $x((0),(3),(0))
31
33 Slicing is a basic, extremely common operation, and PDL's slice method
34 would be cumbersome to use in many cases. "PDL::NiceSlice" rectifies
35 that by incorporating new slicing syntax directly into the language via
36 a perl source filter (see the perlfilter man page). NiceSlice adds no
37 new functionality, only convenient syntax.
38 NiceSlice is loaded automatically in the perldl or pdl2 shell, but (to
40 avoid conflicts with other modules) must be loaded explicitly in
41 standalone perl/PDL scripts (see below). If you prefer not to use a
42 prefilter on your standalone scripts, you can use the slice method in
43 those scripts, rather than the more compact NiceSlice constructs.
44
46 The new slicing syntax can be switched on and off in scripts and perl
47 modules by using or unloading "PDL::NiceSlice".
48 But now back to scripts and modules. Everything after "use
50 PDL::NiceSlice" will be translated and you can use the new slicing
51 syntax. Source filtering will continue until the end of the file is
52 encountered. You can stop sourcefiltering before the end of the file
53 by issuing a "no PDL::NiceSlice" statement.
54 Here is an example:
56 use PDL::NiceSlice;
58 # this code will be translated
60 # and you can use the new slicing syntax
61 no PDL::NiceSlice;
63 # this code won't
65 # and the new slicing syntax will raise errors!
66 See also Filter::Simple and example in this distribution for further
68 examples.
69 NOTE: Unlike "normal" modules you need to include a "use
71 PDL::NiceSlice" call in each and every file that contains code that
72 uses the new slicing syntax. Imagine the following situation: a file
73 test0.pl
74 # start test0.pl
76 use PDL;
77 use PDL::NiceSlice;
78 $x = sequence 10;
80 print $x(0:4),"\n";
81 require 'test1.pl';
83 # end test0.pl
84 that "require"s a second file test1.pl
86 # begin test1.pl
88 $aa = sequence 11;
89 print $aa(0:7),"\n";
90 1;
91 # end test1.pl
92 Following conventional perl wisdom everything should be alright since
94 we "use"d "PDL" and "PDL::NiceSlice" already from within test0.pl and
95 by the time test1.pl is "require"d things should be defined and
96 imported, etc. A quick test run will, however, produce something like
97 the following:
98 perl test0.pl
100 [0 1 2 3 4]
101 syntax error at test1.pl line 3, near "0:"
102 Compilation failed in require at test0.pl line 7.
103 This can be fixed by adding the line
105 use PDL::NiceSlice;
107 "before" the code in test1.pl that uses the new slicing syntax (to play
109 safe just include the line near the top of the file), e.g.
110 # begin corrected test1.pl
112 use PDL::NiceSlice;
113 $aa = sequence 11;
114 print $aa(0:7),"\n";
115 1;
116 # end test1.pl
117 Now things proceed more smoothly
119 perl test0.pl
121 [0 1 2 3 4]
122 [0 1 2 3 4 5 6 7]
123 Note that we don't need to issue "use PDL" again. "PDL::NiceSlice" is
125 a somewhat funny module in that respect. It is a consequence of the way
126 source filtering works in Perl (see also the IMPLEMENTATION section
127 below).
128 evals and "PDL::NiceSlice"
130 Due to "PDL::NiceSlice" being a source filter it won't work in the
131 usual way within evals. The following will not do what you want:
132 $x = sequence 10;
134 eval << 'EOE';
135 use PDL::NiceSlice;
137 $y = $x(0:5);
138 EOE
140 print $y;
141 Instead say:
143 use PDL::NiceSlice;
145 $x = sequence 10;
146 eval << 'EOE';
147 $y = $x(0:5);
149 EOE
151 print $y;
152 Source filters must be executed at compile time to be effective. And
154 "PDL::NiceFilter" is just a source filter (although it is not
155 necessarily obvious for the casual user).
156
158 Using "PDL::NiceSlice" slicing piddles becomes so much easier since,
159 first of all, you don't need to make explicit method calls. No
160 $pdl->slice(....);
162 calls, etc. Instead, "PDL::NiceSlice" introduces two ways in which to
164 slice piddles without too much typing:
165 · using parentheses directly following a scalar variable name, for
167 example
168 $c = $y(0:-3:4,(0));
170 · using the so called default method invocation in which the piddle
172 object is treated as if it were a reference to a subroutine (see also
173 perlref). Take this example that slices a piddle that is part of a
174 perl list @b:
175 $c = $b[0]->(0:-3:4,(0));
177 The format of the argument list is the same for both types of
179 invocation and will be explained in more detail below.
180 Parentheses following a scalar variable name
182 An arglist in parentheses following directly after a scalar variable
183 name that is not preceded by "&" will be resolved as a slicing command,
184 e.g.
185 $x(1:4) .= 2; # only use this syntax on piddles
187 $sum += $x(,(1));
188 However, if the variable name is immediately preceded by a "&", for
190 example
191 &$x(4,5);
193 it will not be interpreted as a slicing expression. Rather, to avoid
195 interfering with the current subref syntax, it will be treated as an
196 invocation of the code reference $x with argumentlist "(4,5)".
197 The $x(ARGS) syntax collides in a minor way with the perl syntax. In
199 particular, ``foreach $var(LIST)'' appears like a PDL slicing call.
200 NiceSlice avoids translating the ``for $var(LIST)'' and ``foreach
201 $var(LIST)'' constructs for this reason. Since you can't use just any
202 old lvalue expression in the 'foreach' 'for' constructs -- only a real
203 perl scalar will do -- there's no functionality lost. If later
204 versions of perl accept ``foreach <lvalue-expr> (LIST)'', then you can
205 use the code ref syntax, below, to get what you want.
206 The default method syntax
208 The second syntax that will be recognized is what I called the default
209 method syntax. It is the method arrow "->" directly followed by an open
210 parenthesis, e.g.
211 $x->xchg(0,1)->(($pos)) .= 0;
213 Note that this conflicts with the use of normal code references, since
215 you can write in plain Perl
216 $sub = sub { print join ',', @_ };
218 $sub->(1,'a');
219 NOTE: Once "use PDL::NiceSlice" is in effect (you can always switch it
221 off with a line "no PDL::NiceSlice;" anywhere in the script) the source
222 filter will incorrectly replace the above call to $sub with an
223 invocation of the slicing method. This is one of the pitfalls of using
224 a source filter that doesn't know anything about the runtime type of a
225 variable (cf. the Implementation section).
226 This shouldn't be a major problem in practice; a simple workaround is
228 to use the "&"-way of calling subrefs, e.g.:
229 $sub = sub { print join ',', @_ };
231 &$sub(1,'a');
232 When to use which syntax?
234 Why are there two different ways to invoke slicing? The first syntax
235 "$x(args)" doesn't work with chained method calls. E.g.
236 $x->xchg(0,1)(0);
238 won't work. It can only be used directly following a valid perl
240 variable name. Instead, use the default method syntax in such cases:
241 $x->xchg(0,1)->(0);
243 Similarly, if you have a list of piddles @pdls:
245 $y = $pdls[5]->(0:-1);
247 The argument list
249 The argument list is a comma separated list. Each argument specifies
250 how the corresponding dimension in the piddle is sliced. In contrast to
251 usage of the slice method the arguments should not be quoted. Rather
252 freely mix literals (1,3,etc), perl variables and function invocations,
253 e.g.
254 $x($pos-1:$end,myfunc(1,3)) .= 5;
256 There can even be other slicing commands in the arglist:
258 $x(0:-1:$pdl($step)) *= 2;
260 NOTE: If you use function calls in the arglist make sure that you use
262 parentheses around their argument lists. Otherwise the source filter
263 will get confused since it splits the argument list on commas that are
264 not protected by parentheses. Take the following example:
265 sub myfunc { return 5*$_[0]+$_[1] }
267 $x = sequence 10;
268 $sl = $x(0:myfunc 1, 2);
269 print $sl;
270 PDL barfed: Error in slice:Too many dims in slice
271 Caught at file /usr/local/bin/perldl, line 232, pkg main
272 The simple fix is
274 $sl = $x(0:myfunc(1, 2));
276 print $sl;
277 [0 1 2 3 4 5 6 7]
278 Note that using prototypes in the definition of myfunc does not help.
280 At this stage the source filter is simply not intelligent enough to
281 make use of this information. So beware of this subtlety.
282 Another pitfall to be aware of: currently, you can't use the
284 conditional operator in slice expressions (i.e., "?:", since the parser
285 confuses them with ranges). For example, the following will cause an
286 error:
287 $x = sequence 10;
289 $y = rand > 0.5 ? 0 : 1; # this one is ok
290 print $x($y ? 1 : 2); # error !
291 syntax error at (eval 59) line 3, near "1,
292 For the moment, just try to stay clear of the conditional operator in
294 slice expressions (or provide us with a patch to the parser to resolve
295 this issue ;).
296 Modifiers
298 Following a suggestion originally put forward by Karl Glazebrook the
299 latest versions of "PDL::NiceSlice" implement modifiers in slice
300 expressions. Modifiers are convenient shorthands for common variations
301 on PDL slicing. The general syntax is
302 $pdl(<slice>;<modifier>)
304 Four modifiers are currently implemented:
306 · "_" : flatten the piddle before applying the slice expression. Here
308 is an example
309 $y = sequence 3, 3;
311 print $y(0:-2;_); # same as $y->flat->(0:-2)
312 [0 1 2 3 4 5 6 7]
313 which is quite different from the same slice expression without the
315 modifier
316 print $y(0:-2);
318 [
319 [0 1]
320 [3 4]
321 [6 7]
322 ]
323 · "|" : sever the link to the piddle, e.g.
325 $x = sequence 10;
327 $y = $x(0:2;|)++; # same as $x(0:2)->sever++
328 print $y;
329 [1 2 3]
330 print $x; # check if $x has been modified
331 [0 1 2 3 4 5 6 7 8 9]
332 · "?" : short hand to indicate that this is really a where expression
334 As expressions like
336 $x->where($x>5)
338 are used very often you can write that shorter as
340 $x($x>5;?)
342 With the "?"-modifier the expression preceding the modifier is not
344 really a slice expression (e.g. ranges are not allowed) but rather
345 an expression as required by the where method. For example, the
346 following code will raise an error:
347 $x = sequence 10;
349 print $x(0:3;?);
350 syntax error at (eval 70) line 3, near "0:"
351 That's about all there is to know about this one.
353 · "-" : squeeze out any singleton dimensions. In less technical
355 terms: reduce the number of dimensions (potentially) by deleting
356 all dims of size 1. It is equivalent to doing a reshape(-1). That
357 can be very handy if you want to simplify the results of slicing
358 operations:
359 $x = ones 3, 4, 5;
361 $y = $x(1,0;-); # easier to type than $x((1),(0))
362 print $y->info;
363 PDL: Double D [5]
364 It also provides a unique opportunity to have smileys in your code!
366 Yes, PDL gives new meaning to smileys.
367 Combining modifiers
369 Several modifiers can be used in the same expression, e.g.
370 $c = $x(0;-|); # squeeze and sever
372 Other combinations are just as useful, e.g. ";_|" to flatten and sever.
374 The sequence in which modifiers are specified is not important.
375 A notable exception is the "where" modifier ("?") which must not be
377 combined with other flags (let me know if you see a good reason to
378 relax this rule).
379 Repeating any modifier will raise an error:
381 $c = $x(-1:1;|-|); # will cause error
383 NiceSlice error: modifier | used twice or more
384 Modifiers are still a new and experimental feature of "PDL::NiceSlice".
386 I am not sure how many of you are actively using them. Please do so and
387 experiment with the syntax. I think modifiers are very useful and make
388 life a lot easier. Feedback is welcome as usual. The modifier syntax
389 will likely be further tuned in the future but we will attempt to
390 ensure backwards compatibility whenever possible.
391 Argument formats
393 In slice expressions you can use ranges and secondly, piddles as 1D
394 index lists (although compare the description of the "?"-modifier above
395 for an exception).
396 · ranges
398 You can access ranges using the usual ":" separated format:
400 $x($start:$stop:$step) *= 4;
402 Note that you can omit the trailing step which then defaults to 1.
404 Double colons ("::") are not allowed to avoid clashes with Perl's
405 namespace syntax. So if you want to use steps different from the
406 default you have to also at least specify the stop position.
407 Examples:
408 $x(::2); # this won't work (in the way you probably intended)
410 $x(:-1:2); # this will select every 2nd element in the 1st dim
411 Just as with slice negative indices count from the end of the
413 dimension backwards with "-1" being the last element. If the start
414 index is larger than the stop index the resulting piddle will have
415 the elements in reverse order between these limits:
416 print $x(-2:0:2);
418 [8 6 4 2 0]
419 A single index just selects the given index in the slice
421 print $x(5);
423 [5]
424 Note, however, that the corresponding dimension is not removed from
426 the resulting piddle but rather reduced to size 1:
427 print $x(5)->info
429 PDL: Double D [1]
430 If you want to get completely rid of that dimension enclose the index
432 in parentheses (again similar to the slice syntax):
433 print $x((5));
435 5
436 In this particular example a 0D piddle results. Note that this syntax
438 is only allowed with a single index. All these will be errors:
439 print $x((0,4)); # will work but not in the intended way
441 print $x((0:4)); # compile time error
442 An empty argument selects the whole dimension, in this example all of
444 the first dimension:
445 print $x(,(0));
447 Alternative ways to select a whole dimension are
449 $x = sequence 5, 5;
451 print $x(:,(0));
452 print $x(0:-1,(0));
453 print $x(:-1,(0));
454 print $x(0:,(0));
455 Arguments for trailing dimensions can be omitted. In that case these
457 dimensions will be fully kept in the sliced piddle:
458 $x = random 3,4,5;
460 print $x->info;
461 PDL: Double D [3,4,5]
462 print $x((0))->info;
463 PDL: Double D [4,5]
464 print $x((0),:,:)->info; # a more explicit way
465 PDL: Double D [4,5]
466 print $x((0),,)->info; # similar
467 PDL: Double D [4,5]
468 · dummy dimensions
470 As in slice, you can insert a dummy dimension by preceding a single
472 index argument with '*'. A lone '*' inserts a dummy dimension of
473 order 1; a '*' followed by a number inserts a dummy dimension of that
474 order.
475 · piddle index lists
477 The second way to select indices from a dimension is via 1D piddles
479 of indices. A simple example:
480 $x = random 10;
482 $idx = long 3,4,7,0;
483 $y = $x($idx);
484 This way of selecting indices was previously only possible using dice
486 ("PDL::NiceSlice" attempts to unify the "slice" and "dice"
487 interfaces). Note that the indexing piddles must be 1D or 0D. Higher
488 dimensional piddles as indices will raise an error:
489 $x = sequence 5, 5;
491 $idx2 = ones 2,2;
492 $sum = $x($idx2)->sum;
493 piddle must be <= 1D at /home/XXXX/.perldlrc line 93
494 Note that using index piddles is not as efficient as using ranges.
496 If you can represent the indices you want to select using a range use
497 that rather than an equivalent index piddle. In particular, memory
498 requirements are increased with index piddles (and execution time may
499 be longer). That said, if an index piddle is the way to go use it!
500 As you might have expected ranges and index piddles can be freely mixed
502 in slicing expressions:
503 $x = random 5, 5;
505 $y = $x(-1:2,pdl(3,0,1));
506 piddles as indices in ranges
508 You can use piddles to specify indices in ranges. No need to turn them
509 into proper perl scalars with the new slicing syntax. However, make
510 sure they contain not more than one element! Otherwise a runtime error
511 will be triggered. First a couple of examples that illustrate proper
512 usage:
513 $x = sequence 5, 5;
515 $rg = pdl(1,-1,3);
516 print $x($rg(0):$rg(1):$rg(2),2);
517 [
518 [11 14]
519 ]
520 print $x($rg+1,:$rg(0));
521 [
522 [2 0 4]
523 [7 5 9]
524 ]
525 The next one raises an error
527 print $x($rg+1,:$rg(0:1));
529 multielement piddle where only one allowed at XXX/Core.pm line 1170.
530 The problem is caused by using the 2-element piddle "$rg(0:1)" as the
532 stop index in the second argument ":$rg(0:1)" that is interpreted as a
533 range by "PDL::NiceSlice". You can use multielement piddles as index
534 piddles as described above but not in ranges. And "PDL::NiceSlice"
535 treats any expression with unprotected ":"'s as a range. Unprotected
536 means as usual "not occurring between matched parentheses".
537
539 "PDL::NiceSlice" exploits the ability of Perl to use source filtering
540 (see also perlfilter). A source filter basically filters (or rewrites)
541 your perl code before it is seen by the compiler. "PDL::NiceSlice"
542 searches through your Perl source code and when it finds the new
543 slicing syntax it rewrites the argument list appropriately and splices
544 a call to the "slice" method using the modified arg list into your perl
545 code. You can see how this works in the perldl or pdl2 shells by
546 switching on reporting (see above how to do that).
547
549 Conditional operator
550 The conditional operator can't be used in slice expressions (see
551 above).
552 The "DATA" file handle
554 Note: To avoid clobbering the "DATA" filehandle "PDL::NiceSlice"
555 switches itself off when encountering the "__END__" or "__DATA__"
556 tokens. This should not be a problem for you unless you use
557 "SelfLoader" to load PDL code including the new slicing from that
558 section. It is even desirable when working with Inline::Pdlpp, see
559 below.
560 Possible interaction with Inline::Pdlpp
562 There is currently an undesired interaction between "PDL::NiceSlice"
563 and the new Inline::Pdlpp module (currently only in PDL CVS). Since PP
564 code generally contains expressions of the type "$var()" (to access
565 piddles, etc) "PDL::NiceSlice" recognizes those incorrectly as slice
566 expressions and does its substitutions. This is not a problem if you
567 use the "DATA" section for your Pdlpp code -- the recommended place for
568 Inline code anyway. In that case "PDL::NiceSlice" will have switched
569 itself off before encountering any Pdlpp code (see above):
570 # use with Inline modules
572 use PDL;
573 use PDL::NiceSlice;
574 use Inline Pdlpp;
575 $x = sequence(10);
577 print $x(0:5);
578 __END__
580 __Pdlpp__
582 ... inline stuff
584 Otherwise switch "PDL::NiceSlice" explicitly off around the
586 Inline::Pdlpp code:
587 use PDL::NiceSlice;
589 $x = sequence 10;
591 $x(0:3)++;
592 $x->inc;
593 no PDL::NiceSlice; # switch off before Pdlpp code
595 use Inline Pdlpp => "Pdlpp source code";
596 The cleaner solution is to always stick with the "DATA" way of
598 including your "Inline" code as in the first example. That way you keep
599 your nice Perl code at the top and all the ugly Pdlpp stuff etc at the
600 bottom.
601 Bug reports
603 Feedback and bug reports are welcome. Please include an example that
604 demonstrates the problem. Log bug reports in the PDL issues tracker at
605 <https://github.com/PDLPorters/pdl/issues> or send them to the pdl-
606 devel mailing list (see <http://pdl.perl.org/?page=mailing-lists>).
607
609 Copyright (c) 2001, 2002 Christian Soeller. All Rights Reserved. This
610 module is free software. It may be used, redistributed and/or modified
611 under the same terms as PDL itself (see <http://pdl.perl.org>).
612perl v5.32.0 2020-09-17 NiceSlice(3)