lib/PDL/Slices.pm

filter: Statementstmt 100% 14 / 14 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 3 / 3 Podpod n/a totaltotal 100% 17 / 17 CC 1 SCAR 0.0
CC
1
Cov
100%
BEGIN
1.0
BEGIN
1.0
BEGIN
1.0
CRAP 1.0
« lib/PDL/Primitive.pm ↑ Summary lib/PDL/Ufunc.pm »
1 #
2 # GENERATED WITH PDL::PP from lib/PDL/Slices.pd! Don't modify!
3 #
4 package PDL::Slices;
5  
6 71 our @EXPORT_OK = qw(index index1d index2d indexND indexNDb rangeb rld rle rlevec rldvec rleseq rldseq rleND rldND _clump_int xchg mv using meshgrid lags splitdim rotate broadcastI unbroadcast dice dice_axis slice diagonal );
7 71 our %EXPORT_TAGS = (Func=>\@EXPORT_OK);
8  
9 71 ▶use PDL::Core;
Subroutine BEGIN: called CC=1 SCAR=0.0
10 71 ▶use PDL::Exporter;
Subroutine BEGIN: called CC=1 SCAR=0.0
11 71 ▶use DynaLoader;
Subroutine BEGIN: called CC=1 SCAR=0.0
12  
13  
14
15 71 our @ISA = ( 'PDL::Exporter','DynaLoader' );
16 71 push @PDL::Core::PP, __PACKAGE__;
17 71 bootstrap PDL::Slices ;
18  
19  
20  
21  
22  
23  
24  
25  
26 #line 5 "lib/PDL/Slices.pd"
27  
28 =head1 NAME
29  
30 PDL::Slices -- Indexing, slicing, and dicing
31  
32 =head1 SYNOPSIS
33  
34 use PDL;
35 $x = ones(3,3);
36 $y = $x->slice('-1:0,(1)');
37 $c = $x->dummy(2);
38  
39 =head1 DESCRIPTION
40  
41 This package provides many of the powerful PerlDL core index
42 manipulation routines. These routines mostly allow two-way data flow,
43 so you can modify your data in the most convenient representation.
44 For example, you can make a 1000x1000 unit matrix with
45  
46 $x = zeroes(1000,1000);
47 $x->diagonal(0,1) ++;
48  
49 which is quite efficient. See L<PDL::Indexing> and L<PDL::Tips> for
50 more examples. As of 2.090, backward dataflow will be turned off if any
51 input has inward-only dataflow, to avoid creating "loops". See
52 L<PDL::Dataflow> for more.
53  
54 Slicing is so central to the PDL language that a special compile-time
55 syntax has been introduced to handle it compactly; see L<PDL::NiceSlice>
56 for details.
57  
58 PDL indexing and slicing functions usually include two-way data flow,
59 so that you can separate the actions of reshaping your data structures
60 and modifying the data themselves. Two special methods, L</copy> and
61 L</sever>, help you control the data flow connection between related
62 variables.
63  
64 $y = $x->slice("1:3"); # Slice maintains a link between $x and $y.
65 $y += 5; # $x is changed!
66  
67 If you want to force a physical copy and no data flow, you can copy or
68 sever the slice expression:
69  
70 $y = $x->slice("1:3")->copy;
71 $y += 5; # $x is not changed.
72  
73 $y = $x->slice("1:3")->sever;
74 $y += 5; # $x is not changed.
75  
76 The difference between C<sever> and C<copy> is that sever acts on (and
77 returns) its argument, while copy produces a disconnected copy. If you
78 say
79  
80 $y = $x->slice("1:3");
81 $c = $y->sever;
82  
83 then the variables C<$y> and C<$c> point to the same object but with
84 C<-E<gt>copy> they would not.
85  
86 =cut
87  
88 use strict;
89 use warnings;
90 use PDL::Core ':Internal';
91 use Scalar::Util 'blessed';
92 #line 93 "lib/PDL/Slices.pm"
93  
94  
95 =head1 FUNCTIONS
96  
97 =cut
98  
99  
100  
101  
102  
103  
104 =head2 index
105  
106 =for sig
107  
108 Signature: (a(n); indx ind(); [oca] c())
109 Types: (sbyte byte short ushort long ulong indx ulonglong longlong
110 float double ldouble cfloat cdouble cldouble)
111  
112 =for usage
113  
114 $c = index($a, $ind);
115 $c = $a->index($ind); # method call
116 $a->index($ind) .= $data; # usable as lvalue
117  
118 =for ref
119  
120 C<index>, C<index1d>, and C<index2d> provide rudimentary index indirection.
121  
122 =for example
123  
124 $c = index($source,$ind);
125 $c = index1d($source,$ind);
126 $c = index2d($source2,$ind1,$ind2);
127  
128 use the C<$ind> variables as indices to look up values in C<$source>.
129 The three routines broadcast slightly differently.
130  
131 =over 3
132  
133 =item *
134  
135 C<index> uses direct broadcasting for 1-D indexing across the 0 dim
136 of C<$source>. It can broadcast over source broadcast dims or index broadcast
137 dims, but not (easily) both: If C<$source> has more than 1
138 dimension and C<$ind> has more than 0 dimensions, they must agree in
139 a broadcasting sense.
140  
141 =item *
142  
143 C<index1d> uses a single active dim in C<$ind> to produce a list of
144 indexed values in the 0 dim of the output - it is useful for
145 collapsing C<$source> by indexing with a single row of values along
146 C<$source>'s 0 dimension. The output has the same number of dims as
147 C<$source>. The 0 dim of the output has size 1 if C<$ind> is a
148 scalar, and the same size as the 0 dim of C<$ind> if it is not. If
149 C<$ind> and C<$source> both have more than 1 dim, then all dims higher
150 than 0 must agree in a broadcasting sense.
151  
152 =item *
153  
154 C<index2d> works like C<index> but uses separate ndarrays for X and Y
155 coordinates. For more general N-dimensional indexing, see the
156 L<PDL::NiceSlice> syntax or L<PDL::Slices> (in particular C<slice>,
157 C<indexND>, and C<range>).
158  
159 =back
160  
161 These functions are two-way, i.e. after
162  
163 $c = $x->index(pdl[0,5,8]);
164 $c .= pdl [0,2,4];
165  
166 the changes in C<$c> will flow back to C<$x>.
167  
168 C<index> provids simple broadcasting: multiple-dimensioned arrays are treated
169 as collections of 1-D arrays, so that
170  
171 $x = xvals(10,10)+10*yvals(10,10);
172 $y = $x->index(3);
173 $c = $x->index(9-xvals(10));
174  
175 puts a single column from C<$x> into C<$y>, and puts a single element
176 from each column of C<$x> into C<$c>. If you want to extract multiple
177 columns from an array in one operation, see L</dice> or
178 L</indexND>.
179  
180 =pod
181  
182 Broadcasts over its inputs.
183 Creates data-flow back and forth by default.
184  
185 =for bad
186  
187 index barfs if any of the index values are bad.
188  
189 =cut
190  
191  
192  
193  
194 *index = \&PDL::index;
195  
196  
197  
198  
199  
200  
201 =head2 index1d
202  
203 =for sig
204  
205 Signature: (a(n); indx ind(m); [oca] c(m))
206 Types: (sbyte byte short ushort long ulong indx ulonglong longlong
207 float double ldouble cfloat cdouble cldouble)
208  
209 =for usage
210  
211 $c = index1d($a, $ind);
212 $c = $a->index1d($ind); # method call
213 $a->index1d($ind) .= $data; # usable as lvalue
214  
215 =for ref
216  
217 C<index>, C<index1d>, and C<index2d> provide rudimentary index indirection.
218  
219 =for example
220  
221 $c = index($source,$ind);
222 $c = index1d($source,$ind);
223 $c = index2d($source2,$ind1,$ind2);
224  
225 use the C<$ind> variables as indices to look up values in C<$source>.
226 The three routines broadcast slightly differently.
227  
228 =over 3
229  
230 =item *
231  
232 C<index> uses direct broadcasting for 1-D indexing across the 0 dim
233 of C<$source>. It can broadcast over source broadcast dims or index broadcast
234 dims, but not (easily) both: If C<$source> has more than 1
235 dimension and C<$ind> has more than 0 dimensions, they must agree in
236 a broadcasting sense.
237  
238 =item *
239  
240 C<index1d> uses a single active dim in C<$ind> to produce a list of
241 indexed values in the 0 dim of the output - it is useful for
242 collapsing C<$source> by indexing with a single row of values along
243 C<$source>'s 0 dimension. The output has the same number of dims as
244 C<$source>. The 0 dim of the output has size 1 if C<$ind> is a
245 scalar, and the same size as the 0 dim of C<$ind> if it is not. If
246 C<$ind> and C<$source> both have more than 1 dim, then all dims higher
247 than 0 must agree in a broadcasting sense.
248  
249 =item *
250  
251 C<index2d> works like C<index> but uses separate ndarrays for X and Y
252 coordinates. For more general N-dimensional indexing, see the
253 L<PDL::NiceSlice> syntax or L<PDL::Slices> (in particular C<slice>,
254 C<indexND>, and C<range>).
255  
256 =back
257  
258 These functions are two-way, i.e. after
259  
260 $c = $x->index(pdl[0,5,8]);
261 $c .= pdl [0,2,4];
262  
263 the changes in C<$c> will flow back to C<$x>.
264  
265 C<index> provids simple broadcasting: multiple-dimensioned arrays are treated
266 as collections of 1-D arrays, so that
267  
268 $x = xvals(10,10)+10*yvals(10,10);
269 $y = $x->index(3);
270 $c = $x->index(9-xvals(10));
271  
272 puts a single column from C<$x> into C<$y>, and puts a single element
273 from each column of C<$x> into C<$c>. If you want to extract multiple
274 columns from an array in one operation, see L</dice> or
275 L</indexND>.
276  
277 =pod
278  
279 Broadcasts over its inputs.
280 Creates data-flow back and forth by default.
281  
282 =for bad
283  
284 index1d propagates BAD index elements to the output variable.
285  
286 =cut
287  
288  
289  
290  
291 *index1d = \&PDL::index1d;
292  
293  
294  
295  
296  
297  
298 =head2 index2d
299  
300 =for sig
301  
302 Signature: (a(na,nb); indx inda(); indx indb(); [oca] c())
303 Types: (sbyte byte short ushort long ulong indx ulonglong longlong
304 float double ldouble cfloat cdouble cldouble)
305  
306 =for usage
307  
308 $c = index2d($a, $inda, $indb);
309 $c = $a->index2d($inda, $indb); # method call
310 $a->index2d($inda, $indb) .= $data; # usable as lvalue
311  
312 =for ref
313  
314 C<index>, C<index1d>, and C<index2d> provide rudimentary index indirection.
315  
316 =for example
317  
318 $c = index($source,$ind);
319 $c = index1d($source,$ind);
320 $c = index2d($source2,$ind1,$ind2);
321  
322 use the C<$ind> variables as indices to look up values in C<$source>.
323 The three routines broadcast slightly differently.
324  
325 =over 3
326  
327 =item *
328  
329 C<index> uses direct broadcasting for 1-D indexing across the 0 dim
330 of C<$source>. It can broadcast over source broadcast dims or index broadcast
331 dims, but not (easily) both: If C<$source> has more than 1
332 dimension and C<$ind> has more than 0 dimensions, they must agree in
333 a broadcasting sense.
334  
335 =item *
336  
337 C<index1d> uses a single active dim in C<$ind> to produce a list of
338 indexed values in the 0 dim of the output - it is useful for
339 collapsing C<$source> by indexing with a single row of values along
340 C<$source>'s 0 dimension. The output has the same number of dims as
341 C<$source>. The 0 dim of the output has size 1 if C<$ind> is a
342 scalar, and the same size as the 0 dim of C<$ind> if it is not. If
343 C<$ind> and C<$source> both have more than 1 dim, then all dims higher
344 than 0 must agree in a broadcasting sense.
345  
346 =item *
347  
348 C<index2d> works like C<index> but uses separate ndarrays for X and Y
349 coordinates. For more general N-dimensional indexing, see the
350 L<PDL::NiceSlice> syntax or L<PDL::Slices> (in particular C<slice>,
351 C<indexND>, and C<range>).
352  
353 =back
354  
355 These functions are two-way, i.e. after
356  
357 $c = $x->index(pdl[0,5,8]);
358 $c .= pdl [0,2,4];
359  
360 the changes in C<$c> will flow back to C<$x>.
361  
362 C<index> provids simple broadcasting: multiple-dimensioned arrays are treated
363 as collections of 1-D arrays, so that
364  
365 $x = xvals(10,10)+10*yvals(10,10);
366 $y = $x->index(3);
367 $c = $x->index(9-xvals(10));
368  
369 puts a single column from C<$x> into C<$y>, and puts a single element
370 from each column of C<$x> into C<$c>. If you want to extract multiple
371 columns from an array in one operation, see L</dice> or
372 L</indexND>.
373  
374 =pod
375  
376 Broadcasts over its inputs.
377 Creates data-flow back and forth by default.
378  
379 =for bad
380  
381 index2d barfs if either of the index values are bad.
382  
383 =cut
384  
385  
386  
387  
388 *index2d = \&PDL::index2d;
389  
390  
391  
392  
393  
394 #line 222 "lib/PDL/Slices.pd"
395  
396 =head2 indexNDb
397  
398 =for ref
399  
400 Backwards-compatibility alias for indexND
401  
402 =head2 indexND
403  
404 =for ref
405  
406 Find selected elements in an N-D ndarray, with optional boundary handling
407  
408 =for example
409  
410 $out = $source->indexND( $index, [$method] )
411  
412 $source = 10*xvals(10,10) + yvals(10,10);
413 $index = pdl([[2,3],[4,5]],[[6,7],[8,9]]);
414 print $source->indexND( $index );
415  
416 [
417 [23 45]
418 [67 89]
419 ]
420  
421 IndexND collapses C<$index> by lookup into C<$source>. The
422 0th dimension of C<$index> is treated as coordinates in C<$source>, and
423 the return value has the same dimensions as the rest of C<$index>.
424 The returned elements are looked up from C<$source>. Dataflow
425 works -- propagated assignment flows back into C<$source>.
426  
427 IndexND and IndexNDb were originally separate routines but they are both
428 now implemented as a call to L</range>, and have identical syntax to
429 one another.
430  
431 SEE ALSO:
432  
433 L<PDL::Primitive/whichND> returns N-D indices into a multidimensional
434 PDL, suitable for feeding to this.
435  
436 =cut
437  
438 sub PDL::indexND :lvalue {
439 my($source,$index, $boundary) = @_;
440 return PDL::range($source,$index,undef,$boundary);
441 }
442  
443 *PDL::indexNDb = \&PDL::indexND;
444  
445 sub PDL::range :lvalue {
446 my($source,$ind,$sz,$bound) = @_;
447 # Convert to indx type up front (also handled in rangeb if necessary)
448 my $index = (ref $ind && UNIVERSAL::isa($ind,'PDL') && $ind->type eq 'indx') ? $ind : indx($ind);
449 my $size = defined($sz) ? PDL->pdl($sz) : undef;
450 # Handle empty PDL case: return a properly constructed Empty.
451 if ($index->isempty) {
452 my @sdims = $source->dims;
453 splice @sdims, 0, $index->dim(0) + ($index->dim(0)==0); # added term is to treat Empty[0] like a single empty coordinate
454 unshift @sdims, $size->list if defined $size;
455 my @index_dims = ((0) x ($index->ndims-1));
456 @index_dims = 0 if !@index_dims; # always at least one 0
457 return PDL->new_from_specification(@index_dims, @sdims);
458 }
459 $index = $index->dummy(0,1) unless $index->ndims;
460 # Pack boundary string if necessary
461 if (defined $bound) {
462 if (ref $bound eq 'ARRAY') {
463 my ($s,$el);
464 foreach $el (@$bound) {
465 barf "Illegal boundary value '$el' in range"
466 unless $el =~ m/^([0123fFtTeEpPmM])/;
467 $s .= $1;
468 }
469 $bound = $s;
470 }
471 elsif ($bound !~ m/^[0123ftepx]+$/ && $bound =~ m/^([0123ftepx])/i) {
472 $bound = $1;
473 }
474 }
475 no warnings; # shut up about passing undef into rangeb
476 $source->rangeb($index,$size,$bound);
477 }
478  
479 =head2 range
480  
481 =for ref
482  
483 Extract selected chunks from a source ndarray, with boundary conditions
484  
485 =for example
486  
487 $out = $source->range($index,[$size,[$boundary]])
488  
489 Returns elements or rectangular slices of the original ndarray, indexed by
490 the C<$index> ndarray. C<$source> is an N-dimensional ndarray, and C<$index> is
491 an ndarray whose first dimension has size up to N. Each row of C<$index> is
492 treated as coordinates of a single value or chunk from C<$source>, specifying
493 the location(s) to extract.
494  
495 If you specify a single index location, then range is essentially an expensive
496 slice, with controllable boundary conditions.
497  
498 B<INPUTS>
499  
500 C<$index> and C<$size> can be ndarrays or array refs such as you would
501 feed to L<zeroes|PDL::Core/zeroes> and its ilk. If C<$index>'s 0th dimension
502 has size higher than the number of dimensions in C<$source>, then
503 C<$source> is treated as though it had trivial dummy dimensions of
504 size 1, up to the required size to be indexed by C<$index> -- so if
505 your source array is 1-D and your index array is a list of 3-vectors,
506 you get two dummy dimensions of size 1 on the end of your source array.
507  
508 You can extract single elements or N-D rectangular ranges from C<$source>,
509 by setting C<$size>. If C<$size> is undef or zero, then you get a single
510 sample for each row of C<$index>. This behavior is similar to
511 L</indexNDb>, which is in fact implemented as a call to L</range>.
512  
513 If C<$size> is positive then you get a range of values from C<$source> at
514 each location, and the output has extra dimensions allocated for them.
515 C<$size> can be a scalar, in which case it applies to all dimensions, or an
516 N-vector, in which case each element is applied independently to the
517 corresponding dimension in C<$source>. See below for details.
518  
519 C<$boundary> is a number, string, or list ref indicating the type of
520 boundary conditions to use when ranges reach the edge of C<$source>. If you
521 specify no boundary conditions the default is to forbid boundary violations
522 on all axes. If you specify exactly one boundary condition, it applies to
523 all axes. If you specify more (as elements of a list ref, or as a packed
524 string, see below), then they apply to dimensions in the order in which they
525 appear, and the last one applies to all subsequent dimensions. (This is
526 less difficult than it sounds; see the examples below).
527  
528 =over 3
529  
530 =item 0 (synonyms: 'f','forbid') B<(default)>
531  
532 Ranges are not allowed to cross the boundary of the original PDL. Disallowed
533 ranges throw an error. The errors are thrown at evaluation time, not
534 at the time of the range call (this is the same behavior as L</slice>).
535  
536 =item 1 (synonyms: 't','truncate')
537  
538 Values outside the original ndarray get BAD if you've got bad value
539 support compiled into your PDL and set the badflag for the source PDL;
540 or 0 if you haven't (you must set the badflag if you want BADs for out
541 of bound values, otherwise you get 0). Reverse dataflow works OK for
542 the portion of the child that is in-bounds. The out-of-bounds part of
543 the child is reset to (BAD|0) during each dataflow operation, but
544 execution continues.
545  
546 =item 2 (synonyms: 'e','x','extend')
547  
548 Values that would be outside the original ndarray point instead to the
549 nearest allowed value within the ndarray. See the CAVEAT below on
550 mappings that are not single valued.
551  
552 =item 3 (synonyms: 'p','periodic')
553  
554 Periodic boundary conditions apply: the numbers in $index are applied,
555 strict-modulo the corresponding dimensions of $source. This is equivalent to
556 duplicating the $source ndarray throughout N-D space. See the CAVEAT below
557 about mappings that are not single valued.
558  
559 =item 4 (synonyms: 'm','mirror')
560  
561 Mirror-reflection periodic boundary conditions apply. See the CAVEAT
562 below about mappings that are not single valued.
563  
564 =back
565  
566 The boundary condition identifiers all begin with unique characters, so
567 you can feed in multiple boundary conditions as either a list ref or a
568 packed string. (The packed string is marginally faster to run). For
569 example, the four expressions [0,1], ['forbid','truncate'], ['f','t'],
570 and 'ft' all specify that violating the boundary in the 0th dimension
571 throws an error, and all other dimensions get truncated.
572  
573 If you feed in a single string, it is interpreted as a packed boundary
574 array if all of its characters are valid boundary specifiers (e.g. 'pet'),
575 but as a single word-style specifier if they are not (e.g. 'forbid').
576  
577 Where the source PDL is empty, all non-barfing boundary conditions
578 are changed to truncation, since there is no data to reflect, extend,
579 or mirror.
580  
581 B<OUTPUT>
582  
583 The output broadcasts over both C<$index> and C<$source>. Because implicit
584 broadcasting can happen in a couple of ways, a little thought is needed. The
585 returned dimension list is stacked up like this:
586  
587 (index broadcast dims), (index dims (size)), (source broadcast dims)
588  
589 The first few dims of the output correspond to the extra dims of
590 C<$index> (beyond the 0 dim). They allow you to pick out individual
591 ranges from a large, broadcasted collection.
592  
593 The middle few dims of the output correspond to the size dims
594 specified in C<$size>, and contain the range of values that is extracted
595 at each location in C<$source>. Every nonzero element of C<$size> is copied to
596 the dimension list here, so that if you feed in (for example) C<$size
597 = [2,0,1]> you get an index dim list of C<(2,1)>.
598  
599 The last few dims of the output correspond to extra dims of C<$source> beyond
600 the number of dims indexed by C<$index>. These dims act like ordinary
601 broadcast dims, because adding more dims to C<$source> just tacks extra dims
602 on the end of the output. Each source broadcast dim ranges over the entire
603 corresponding dim of C<$source>.
604  
605 B<Dataflow>: Dataflow is bidirectional.
606  
607 B<Examples>:
608 Here are basic examples of C<range> operation, showing how to get
609 ranges out of a small matrix. The first few examples show extraction
610 and selection of individual chunks. The last example shows
611 how to mark loci in the original matrix (using dataflow).
612  
613 pdl> $src = 10*xvals(10,5)+yvals(10,5)
614 pdl> print $src->range([2,3]) # Cut out a single element
615 23
616 pdl> print $src->range([2,3],1) # Cut out a single 1x1 block
617 [
618 [23]
619 ]
620 pdl> print $src->range([2,3], [2,1]) # Cut a 2x1 chunk
621 [
622 [23 33]
623 ]
624 pdl> print $src->range([[2,3]],[2,1]) # Trivial list of 1 chunk
625 [
626 [
627 [23]
628 [33]
629 ]
630 ]
631 pdl> print $src->range([[2,3],[0,1]], [2,1]) # two 2x1 chunks
632 [
633 [
634 [23 1]
635 [33 11]
636 ]
637 ]
638 pdl> # A 2x2 collection of 2x1 chunks
639 pdl> print $src->range([[[1,1],[2,2]],[[2,3],[0,1]]],[2,1])
640 [
641 [
642 [
643 [11 22]
644 [23 1]
645 ]
646 [
647 [21 32]
648 [33 11]
649 ]
650 ]
651 ]
652 pdl> $src = xvals(5,3)*10+yvals(5,3)
653 pdl> print $src->range(3,1) # Broadcast over y dimension in $src
654 [
655 [30]
656 [31]
657 [32]
658 ]
659  
660 pdl> $src = zeroes(5,4);
661 pdl> $src->range(pdl([2,3],[0,1]),pdl(2,1)) .= xvals(2,2,1) + 1
662 pdl> print $src
663 [
664 [0 0 0 0 0]
665 [2 2 0 0 0]
666 [0 0 0 0 0]
667 [0 0 1 1 0]
668 ]
669  
670 B<CAVEAT>: It's quite possible to select multiple ranges that
671 intersect. In that case, modifying the ranges doesn't have a
672 guaranteed result in the original PDL -- the result is an arbitrary
673 choice among the valid values. For some things that's OK; but for
674 others it's not. In particular, this doesn't work:
675  
676 pdl> $photon_list = PDL::RandVar->new->sample(500)->reshape(2,250)*10
677 pdl> $histogram = zeroes(10,10)
678 pdl> $histogram->range($photon_list,1)++; #not what you wanted
679  
680 The reason is that if two photons land in the same bin, then that bin
681 doesn't get incremented twice. (That may get fixed in a later version...)
682  
683 B<PERMISSIVE RANGING>: If C<$index> has too many dimensions compared
684 to C<$source>, then $source is treated as though it had dummy
685 dimensions of size 1, up to the required number of dimensions. These
686 virtual dummy dimensions have the usual boundary conditions applied to
687 them.
688  
689 If the 0 dimension of C<$index> is ludicrously large (if its size is
690 more than 5 greater than the number of dims in the source PDL) then
691 range will insist that you specify a size in every dimension, to make
692 sure that you know what you're doing. That catches a common error with
693 range usage: confusing the initial dim (which is usually small) with another
694 index dim (perhaps of size 1000).
695  
696 If the index variable is Empty, then range() always returns the Empty PDL.
697 If the index variable is not Empty, indexing it always yields a boundary
698 violation. All non-barfing conditions are treated as truncation, since
699 there are no actual data to return.
700  
701 B<EFFICIENCY>: Because C<range> isn't an affine transformation (it
702 involves lookup into a list of N-D indices), it is somewhat
703 memory-inefficient for long lists of ranges, and keeping dataflow open
704 is much slower than for affine transformations (which don't have to copy
705 data around).
706  
707 Doing operations on small subfields of a large range is inefficient
708 because the engine must flow the entire range back into the original
709 PDL with every atomic perl operation, even if you only touch a single element.
710 One way to speed up such code is to sever your range, so that PDL
711 doesn't have to copy the data with each operation, then copy the
712 elements explicitly at the end of your loop. Here's an example that
713 labels each region in a range sequentially, using many small
714 operations rather than a single xvals assignment:
715  
716 ### How to make a collection of small ops run fast with range...
717 $x = $data->range($index, $sizes, $bound)->sever;
718 $aa = $data->range($index, $sizes, $bound);
719 $x($_ - 1) .= $_ for 1..$x->nelem; # Lots of little ops
720 $aa .= $x;
721  
722 C<range> is a perl front-end to a PP function, C<rangeb>. Calling
723 C<rangeb> is marginally faster but requires that you include all arguments.
724  
725 DEVEL NOTES
726  
727 * index broadcast dimensions are effectively clumped internally. This
728 makes it easier to loop over the index array but a little more brain-bending
729 to tease out the algorithm.
730  
731 =cut
732 #line 733 "lib/PDL/Slices.pm"
733  
734  
735 =head2 rangeb
736  
737 =for sig
738  
739 Signature: (PARENT(); [oca]CHILD(); pdl *ind_pdl; SV *size_sv; SV *boundary_sv)
740 Types: (sbyte byte short ushort long ulong indx ulonglong longlong
741 float double ldouble cfloat cdouble cldouble)
742  
743 =for usage
744  
745 $CHILD = rangeb($PARENT, $ind_pdl, $size_sv, $boundary_sv);
746 $CHILD = $PARENT->rangeb($ind_pdl, $size_sv, $boundary_sv); # method call
747 $PARENT->rangeb($ind_pdl, $size_sv, $boundary_sv) .= $data; # usable as lvalue
748  
749 =for ref
750  
751 Engine for L</range>
752  
753 =for example
754  
755 Same calling convention as L</range>, but you must supply all
756 parameters. C<rangeb> is marginally faster as it makes a direct PP call,
757 avoiding the perl argument-parsing step.
758  
759 =pod
760  
761 Does not broadcast.
762 Creates data-flow back and forth by default.
763  
764 =for bad
765  
766 C<rangeb> processes bad values.
767 It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
768  
769 =cut
770  
771  
772  
773  
774 *rangeb = \&PDL::rangeb;
775  
776  
777  
778  
779  
780  
781 =head2 rld
782  
783 =for sig
784  
785 Signature: (indx a(n); b(n); [o]c(m); IV sumover_max => m)
786 Types: (sbyte byte short ushort long ulong indx ulonglong longlong
787 float double ldouble cfloat cdouble cldouble)
788  
789 =for usage
790  
791 $c = rld($a, $b, $sumover_max);
792 rld($a, $b, $c, $sumover_max); # all arguments given
793 $c = $a->rld($b, $sumover_max); # method call
794 $a->rld($b, $c, $sumover_max);
795  
796 =for ref
797  
798 Run-length decode a vector
799  
800 Given a vector C<$x> of the numbers of instances of values C<$y>, run-length
801 decode to C<$c>.
802  
803 =pod
804  
805 Broadcasts over its inputs.
806  
807 =for bad
808  
809 C<rld> does not process bad values.
810 It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
811  
812 =cut
813  
814  
815  
816  
817  
818 #line 1021 "lib/PDL/Slices.pd"
819 sub PDL::rld {
820 my ($x,$y) = @_;
821 my ($c,$sm) = @_ == 3 ? ($_[2], $_[2]->dim(0)) : (PDL->null, $x->sumover->max->sclr);
822 PDL::_rld_int($x,$y,$c,$sm);
823 $c;
824 }
825 #line 826 "lib/PDL/Slices.pm"
826  
827 *rld = \&PDL::rld;
828  
829  
830  
831  
832  
833  
834 =head2 rle
835  
836 =for sig
837  
838 Signature: (c(n); indx [o]a(m=CALC($SIZE(n))); [o]b(m))
839 Types: (sbyte byte short ushort long ulong indx ulonglong longlong
840 float double ldouble cfloat cdouble cldouble)
841  
842 =for usage
843  
844 ($a, $b) = rle($c);
845 rle($c, $a, $b); # all arguments given
846 ($a, $b) = $c->rle; # method call
847 $c->rle($a, $b);
848  
849 =for ref
850  
851 Run-length encode a vector
852  
853 Given vector C<$c>, generate a vector C<$x> with the number of each
854 element, and a vector C<$y> of the unique values. New in PDL 2.017,
855 only the elements up to the first instance of C<0> in C<$x> are
856 returned, which makes the common use case of a 1-dimensional C<$c> simpler.
857 For broadcast operation, C<$x> and C<$y> will be large enough
858 to hold the largest row of C<$y>, and only the elements up to the
859 first instance of C<0> in each row of C<$x> should be considered.
860  
861 =for example
862  
863 $c = floor(4*random(10));
864 rle($c,$x=null,$y=null);
865 #or
866 ($x,$y) = rle($c);
867  
868 #for $c of shape [10, 4]:
869 $c = floor(4*random(10,4));
870 ($x,$y) = rle($c);
871  
872 #to see the results of each row one at a time:
873 foreach (0..$c->dim(1)-1){
874 my ($as,$bs) = ($x(:,($_)),$y(:,($_)));
875 my ($ta,$tb) = where($as,$bs,$as!=0); #only the non-zero elements of $x
876 print $c(:,($_)) . " rle==> " , ($ta,$tb) , "\trld==> " . rld($ta,$tb) . "\n";
877 }
878  
879 # the inverse of (chance of all 6 3d6 rolls being >= each possible sum)
880 ($nrolls, $ndice, $dmax) = (6, 3, 6);
881 ($x, $x1) = (allaxisvals(($dmax) x $ndice)+1)->sumover->flat->qsort->rle;
882 $y = $x->cumusumover;
883 $yprob1x = $y->slice('-1:0')->double / $y->slice('(-1)');
884 $z = cat($x1, 1 / $yprob1x**$nrolls)->transpose;
885  
886 =pod
887  
888 Broadcasts over its inputs.
889  
890 =for bad
891  
892 C<rle> does not process bad values.
893 It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
894  
895 =cut
896  
897  
898  
899  
900  
901 #line 1051 "lib/PDL/Slices.pd"
902 sub PDL::rle {
903 my $c = shift;
904 my ($x,$y) = @_==2 ? @_ : (null,null);
905 PDL::_rle_int($c,$x,$y);
906 my $max_ind = ($c->ndims<2) ? ($x!=0)->sumover-1 :
907 ($x!=0)->clump(1..$x->ndims-1)->sumover->max->sclr-1;
908 return ($x->slice("0:$max_ind"),$y->slice("0:$max_ind"));
909 }
910 #line 911 "lib/PDL/Slices.pm"
911  
912 *rle = \&PDL::rle;
913  
914  
915  
916  
917  
918  
919 =head2 rlevec
920  
921 =for sig
922  
923 Signature: (c(M,N); indx [o]a(N); [o]b(M,N))
924 Types: (sbyte byte short ushort long ulong indx ulonglong longlong
925 float double ldouble)
926  
927 =for usage
928  
929 ($a, $b) = rlevec($c);
930 rlevec($c, $a, $b); # all arguments given
931 ($a, $b) = $c->rlevec; # method call
932 $c->rlevec($a, $b);
933  
934 =for ref
935  
936 Run-length encode a set of vectors.
937  
938 Higher-order rle(), for use with qsortvec().
939  
940 Given set of vectors $c, generate a vector $a with the number of occurrences of each element
941 (where an "element" is a vector of length $M occurring in $c),
942 and a set of vectors $b containing the unique values.
943 As for rle(), only the elements up to the first instance of 0 in $a should be considered.
944  
945 Can be used together with clump() to run-length encode "values" of arbitrary dimensions.
946 Can be used together with rotate(), cat(), append(), and qsortvec() to count N-grams
947 over a 1d PDL.
948  
949 See also: L</rle>, L<PDL::Ufunc/qsortvec>, L<PDL::Primitive/uniqvec>
950 Contributed by Bryan Jurish E<lt>moocow@cpan.orgE<gt>.
951  
952 =pod
953  
954 Broadcasts over its inputs.
955  
956 =for bad
957  
958 C<rlevec> does not process bad values.
959 It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
960  
961 =cut
962  
963  
964  
965  
966 *rlevec = \&PDL::rlevec;
967  
968  
969  
970  
971  
972  
973 =head2 rldvec
974  
975 =for sig
976  
977 Signature: (indx a(uniqvals); b(M,uniqvals); [o]c(M,decodedvals); IV sumover_max => decodedvals)
978 Types: (sbyte byte short ushort long ulong indx ulonglong longlong
979 float double ldouble)
980  
981 =for usage
982  
983 $c = rldvec($a, $b, $sumover_max);
984 rldvec($a, $b, $c, $sumover_max); # all arguments given
985 $c = $a->rldvec($b, $sumover_max); # method call
986 $a->rldvec($b, $c, $sumover_max);
987  
988 =for ref
989  
990 Run-length decode a set of vectors, akin to a higher-order rld().
991  
992 Given a vector $a() of the number of occurrences of each row, and a set $b()
993 of row-vectors each of length $M, run-length decode to $c().
994  
995 Can be used together with clump() to run-length decode "values" of arbitrary dimensions.
996  
997 Note: $sumover_max is used internally only. Any value provided will be
998 ignored.
999  
1000 See also: L</rld>.
1001 Contributed by Bryan Jurish E<lt>moocow@cpan.orgE<gt>.
1002  
1003 =pod
1004  
1005 Broadcasts over its inputs.
1006  
1007 =for bad
1008  
1009 C<rldvec> does not process bad values.
1010 It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
1011  
1012 =cut
1013  
1014  
1015  
1016  
1017  
1018 #line 1176 "lib/PDL/Slices.pd"
1019 sub PDL::rldvec {
1020 my ($a,$b,$c) = @_;
1021 $c = PDL->null unless defined $c;
1022 my $sm = $c->isnull ? $a->sumover->max->sclr : $c->dim(1);
1023 PDL::_rldvec_int($a,$b,$c,$sm);
1024 return $c;
1025 }
1026 #line 1027 "lib/PDL/Slices.pm"
1027  
1028 *rldvec = \&PDL::rldvec;
1029  
1030  
1031  
1032  
1033  
1034  
1035 =head2 rleseq
1036  
1037 =for sig
1038  
1039 Signature: (c(N); indx [o]a(N); [o]b(N))
1040 Types: (sbyte byte short ushort long ulong indx ulonglong longlong
1041 float double ldouble)
1042  
1043 =for usage
1044  
1045 ($a, $b) = rleseq($c);
1046 rleseq($c, $a, $b); # all arguments given
1047 ($a, $b) = $c->rleseq; # method call
1048 $c->rleseq($a, $b);
1049  
1050 =for ref
1051  
1052 Run-length encode a vector of subsequences.
1053  
1054 Given a vector of $c() of concatenated variable-length, variable-offset subsequences,
1055 generate a vector $a containing the length of each subsequence
1056 and a vector $b containing the subsequence offsets.
1057 As for rle(), only the elements up to the first instance of 0 in $a should be considered.
1058  
1059 See also L</rle>.
1060 Contributed by Bryan Jurish E<lt>moocow@cpan.orgE<gt>.
1061  
1062 =pod
1063  
1064 Broadcasts over its inputs.
1065  
1066 =for bad
1067  
1068 C<rleseq> does not process bad values.
1069 It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
1070  
1071 =cut
1072  
1073  
1074  
1075  
1076 *rleseq = \&PDL::rleseq;
1077  
1078  
1079  
1080  
1081  
1082  
1083 =head2 rldseq
1084  
1085 =for sig
1086  
1087 Signature: (indx a(N); b(N); [o]c(M); IV sumover_max => M)
1088 Types: (sbyte byte short ushort long ulong indx ulonglong longlong
1089 float double ldouble)
1090  
1091 =for usage
1092  
1093 $c = rldseq($a, $b, $sumover_max);
1094 rldseq($a, $b, $c, $sumover_max); # all arguments given
1095 $c = $a->rldseq($b, $sumover_max); # method call
1096 $a->rldseq($b, $c, $sumover_max);
1097  
1098 =for ref
1099  
1100 Run-length decode a subsequence vector.
1101  
1102 Given a vector $a() of sequence lengths
1103 and a vector $b() of corresponding offsets,
1104 decode concatenation of subsequences to $c(),
1105 as for:
1106  
1107 $c = null;
1108 $c = $c->append($b($_)+sequence($a->type,$a($_))) foreach (0..($N-1));
1109  
1110 Note: $sumover_max is used internally only. Any value provided will be
1111 ignored.
1112  
1113 See also: L</rld>.
1114 Contributed by Bryan Jurish E<lt>moocow@cpan.orgE<gt>.
1115  
1116 =pod
1117  
1118 Broadcasts over its inputs.
1119  
1120 =for bad
1121  
1122 C<rldseq> does not process bad values.
1123 It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
1124  
1125 =cut
1126  
1127  
1128  
1129  
1130  
1131 #line 1251 "lib/PDL/Slices.pd"
1132 sub PDL::rldseq {
1133 my ($a,$b,$c) = @_;
1134 $c = PDL->null unless defined $c;
1135 my $sm = $c->isnull ? $a->sumover->max->sclr : $c->dim(1);
1136 PDL::_rldseq_int($a,$b,$c,$sm);
1137 return $c;
1138 }
1139 #line 1140 "lib/PDL/Slices.pm"
1140  
1141 *rldseq = \&PDL::rldseq;
1142  
1143  
1144  
1145  
1146  
1147 #line 1289 "lib/PDL/Slices.pd"
1148  
1149 =head2 rleND
1150  
1151 =for sig
1152  
1153 Signature: (data(@vdims,N); int [o]counts(N); [o]elts(@vdims,N))
1154  
1155 =for ref
1156  
1157 Run-length encode a set of (sorted) n-dimensional values.
1158  
1159 Generalization of rle() and vv_rlevec():
1160 given set of values $data, generate a vector $counts with the number of occurrences of each element
1161 (where an "element" is a matrix of dimensions @vdims occurring as a sequential run over the
1162 final dimension in $data), and a set of vectors $elts containing the elements which begin a run.
1163 Really just a wrapper for clump() and rlevec().
1164  
1165 See also: L</rle>, L</rlevec>.
1166 Contributed by Bryan Jurish E<lt>moocow@cpan.orgE<gt>.
1167  
1168 =cut
1169  
1170 *PDL::rleND = \&rleND;
1171 sub rleND {
1172 my $data = shift;
1173 my @vdimsN = $data->dims;
1174  
1175 ##-- construct output pdls
1176 my $counts = $#_ >= 0 ? $_[0] : PDL->null;
1177 my $elts = $#_ >= 1 ? $_[1] : zeroes($data->type, @vdimsN);
1178  
1179 ##-- guts: call rlevec()
1180 rlevec($data->clump($#vdimsN), $counts, $elts->clump($#vdimsN));
1181  
1182 return ($counts,$elts);
1183 }
1184  
1185 =head2 rldND
1186  
1187 =for sig
1188  
1189 Signature: (int counts(N); elts(@vdims,N); [o]data(@vdims,N);)
1190  
1191 =for ref
1192  
1193 Run-length decode a set of (sorted) n-dimensional values.
1194  
1195 Generalization of rld() and rldvec():
1196 given a vector $counts() of the number of occurrences of each @vdims-dimensioned element,
1197 and a set $elts() of @vdims-dimensioned elements, run-length decode to $data().
1198  
1199 Really just a wrapper for clump() and rldvec().
1200  
1201 See also: L</rld>, L</rldvec>.
1202 Contributed by Bryan Jurish E<lt>moocow@cpan.orgE<gt>.
1203  
1204 =cut
1205  
1206 *PDL::rldND = \&rldND;
1207 sub rldND {
1208 my ($counts,$elts) = (shift,shift);
1209 my @vdimsN = $elts->dims;
1210  
1211 ##-- allocate output pdl if none given
1212 my $data = @_ ? $_[0] : PDL->null;
1213 my $have_null = $data->isnull;
1214  
1215 ##-- guts: call rldvec()
1216 rldvec($counts, $elts->clump($#vdimsN),
1217 $have_null ? $data : $data->clump($#vdimsN));
1218  
1219 ##-- reshape output according to $elts
1220 if ($have_null) {
1221 my @dims = $data->dims;
1222 pop(@vdimsN);
1223 splice(@dims, 0, 1, @vdimsN);
1224 $data->reshape(@dims);
1225 }
1226 return $data;
1227 }
1228 #line 1229 "lib/PDL/Slices.pm"
1229  
1230 *_clump_int = \&PDL::_clump_int;
1231  
1232  
1233  
1234  
1235  
1236  
1237 =head2 xchg
1238  
1239 =for sig
1240  
1241 Signature: (PARENT(); [oca]CHILD(); PDL_Indx n1; PDL_Indx n2)
1242 Types: (sbyte byte short ushort long ulong indx ulonglong longlong
1243 float double ldouble cfloat cdouble cldouble)
1244  
1245 =for usage
1246  
1247 $CHILD = xchg($PARENT, $n1, $n2);
1248 $CHILD = $PARENT->xchg($n1, $n2); # method call
1249 $PARENT->xchg($n1, $n2) .= $data; # usable as lvalue
1250  
1251 =for ref
1252  
1253 exchange two dimensions
1254  
1255 Negative dimension indices count from the end.
1256  
1257 The command
1258  
1259 =for example
1260  
1261 $y = $x->xchg(2,3);
1262  
1263 creates C<$y> to be like C<$x> except that the dimensions 2 and 3
1264 are exchanged with each other i.e.
1265  
1266 $y->at(5,3,2,8) == $x->at(5,3,8,2)
1267  
1268 =pod
1269  
1270 Does not broadcast.
1271 Makes L<virtual affine|PDL::Indexing> ndarrays.
1272 Creates data-flow back and forth by default.
1273  
1274 =for bad
1275  
1276 C<xchg> does not process bad values.
1277 It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
1278  
1279 =cut
1280  
1281  
1282  
1283  
1284 *xchg = \&PDL::xchg;
1285  
1286  
1287  
1288  
1289  
1290 #line 1440 "lib/PDL/Slices.pd"
1291  
1292 =head2 reorder
1293  
1294 =for ref
1295  
1296 Re-orders the dimensions of a PDL based on the supplied list.
1297  
1298 Similar to the L</xchg> method, this method re-orders the dimensions
1299 of a PDL. While the L</xchg> method swaps the position of two dimensions,
1300 the reorder method can change the positions of many dimensions at
1301 once.
1302  
1303 =for usage
1304  
1305 # Completely reverse the dimension order of a 6-Dim array.
1306 $reOrderedPDL = $pdl->reorder(5,4,3,2,1,0);
1307  
1308 The argument to reorder is an array representing where the current dimensions
1309 should go in the new array. In the above usage, the argument to reorder
1310 C<(5,4,3,2,1,0)>
1311 indicates that the old dimensions (C<$pdl>'s dims) should be re-arranged to make the
1312 new pdl (C<$reOrderPDL>) according to the following:
1313  
1314 Old Position New Position
1315 ------------ ------------
1316 5 0
1317 4 1
1318 3 2
1319 2 3
1320 1 4
1321 0 5
1322  
1323 You do not need to specify all dimensions, only a complete set
1324 starting at position 0. (Extra dimensions are left where they are).
1325 This means, for example, that you can reorder() the X and Y dimensions of
1326 an image, and not care whether it is an RGB image with a third dimension running
1327 across color plane.
1328  
1329 =for example
1330  
1331 Example:
1332  
1333 pdl> $x = sequence(5,3,2); # Create a 3-d Array
1334 pdl> p $x
1335 [
1336 [
1337 [ 0 1 2 3 4]
1338 [ 5 6 7 8 9]
1339 [10 11 12 13 14]
1340 ]
1341 [
1342 [15 16 17 18 19]
1343 [20 21 22 23 24]
1344 [25 26 27 28 29]
1345 ]
1346 ]
1347 pdl> p $x->reorder(2,1,0); # Reverse the order of the 3-D PDL
1348 [
1349 [
1350 [ 0 15]
1351 [ 5 20]
1352 [10 25]
1353 ]
1354 [
1355 [ 1 16]
1356 [ 6 21]
1357 [11 26]
1358 ]
1359 [
1360 [ 2 17]
1361 [ 7 22]
1362 [12 27]
1363 ]
1364 [
1365 [ 3 18]
1366 [ 8 23]
1367 [13 28]
1368 ]
1369 [
1370 [ 4 19]
1371 [ 9 24]
1372 [14 29]
1373 ]
1374 ]
1375  
1376 The above is a simple example that could be duplicated by calling
1377 C<$x-E<gt>xchg(0,2)>, but it demonstrates the basic functionality of reorder.
1378  
1379 As this is an index function, any modifications to the
1380 result PDL will change the parent.
1381  
1382 =cut
1383  
1384 sub PDL::reorder :lvalue {
1385 my ($pdl,@newDimOrder) = @_;
1386  
1387 my $arrayMax = $#newDimOrder;
1388  
1389 #Error Checking:
1390 if( $pdl->getndims < scalar(@newDimOrder) ){
1391 my $errString = "PDL::reorder: Number of elements (".scalar(@newDimOrder).") in newDimOrder array exceeds\n";
1392 $errString .= "the number of dims in the supplied PDL (".$pdl->getndims.")";
1393 barf($errString);
1394 }
1395  
1396 # Check to make sure all the dims are within bounds
1397 for my $i(0..$#newDimOrder) {
1398 my $dim = $newDimOrder[$i];
1399 if($dim < 0 || $dim > $#newDimOrder) {
1400 my $errString = "PDL::reorder: Dim index $newDimOrder[$i] out of range in position $i\n(range is 0-$#newDimOrder)";
1401 barf($errString);
1402 }
1403 }
1404  
1405 # Checking that they are all present and also not duplicated is done by broadcast() [I think]
1406  
1407 # a quicker way to do the reorder
1408 return $pdl->broadcast(@newDimOrder)->unbroadcast(0);
1409 }
1410 #line 1411 "lib/PDL/Slices.pm"
1411  
1412  
1413 =head2 mv
1414  
1415 =for sig
1416  
1417 Signature: (PARENT(); [oca]CHILD(); PDL_Indx n1; PDL_Indx n2)
1418 Types: (sbyte byte short ushort long ulong indx ulonglong longlong
1419 float double ldouble cfloat cdouble cldouble)
1420  
1421 =for usage
1422  
1423 $CHILD = mv($PARENT, $n1, $n2);
1424 $CHILD = $PARENT->mv($n1, $n2); # method call
1425 $PARENT->mv($n1, $n2) .= $data; # usable as lvalue
1426  
1427 =for ref
1428  
1429 move a dimension to another position
1430  
1431 The command
1432  
1433 =for example
1434  
1435 $y = $x->mv(4,1);
1436  
1437 creates C<$y> to be like C<$x> except that the dimension 4 is moved to the
1438 place 1, so:
1439  
1440 $y->at(1,2,3,4,5,6) == $x->at(1,5,2,3,4,6);
1441  
1442 The other dimensions are moved accordingly.
1443 Negative dimension indices count from the end.
1444  
1445 =pod
1446  
1447 Does not broadcast.
1448 Makes L<virtual affine|PDL::Indexing> ndarrays.
1449 Creates data-flow back and forth by default.
1450  
1451 =for bad
1452  
1453 C<mv> does not process bad values.
1454 It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
1455  
1456 =cut
1457  
1458  
1459  
1460  
1461 *mv = \&PDL::mv;
1462  
1463  
1464  
1465  
1466  
1467 #line 1610 "lib/PDL/Slices.pd"
1468  
1469 =head2 using
1470  
1471 =for ref
1472  
1473 Returns list of columns requested
1474  
1475 =for usage
1476  
1477 line $pdl->using(1,2);
1478  
1479 Plot, as a line, column 1 of C<$pdl> vs. column 2
1480  
1481 =for example
1482  
1483 pdl> $pdl = rcols("file");
1484 pdl> line $pdl->using(1,2);
1485  
1486 =cut
1487  
1488 *using = \&PDL::using;
1489 sub PDL::using {
1490 my ($x,@ind)=@_;
1491 @ind = list $ind[0] if (blessed($ind[0]) && $ind[0]->isa('PDL'));
1492 foreach (@ind) {
1493 $_ = $x->slice("($_)");
1494 }
1495 @ind;
1496 }
1497  
1498 =head2 meshgrid
1499  
1500 =for ref
1501  
1502 Returns list of given 1-D vectors, but each expanded to match dims using
1503 L<PDL::Core/dummy>.
1504  
1505 =for usage
1506  
1507 meshgrid($vec1, $vec2, $vec3);
1508  
1509 =for example
1510  
1511 print map $_->info, meshgrid(xvals(3), xvals(4), xvals(2));
1512 # PDL: Double D [3,4,2] PDL: Double D [3,4,2] PDL: Double D [3,4,2]
1513  
1514 =cut
1515  
1516 *meshgrid = \&PDL::meshgrid;
1517 sub PDL::meshgrid {
1518 barf "meshgrid: only 1-dimensional inputs" if grep $_->ndims != 1, @_;
1519 return @_ if @_ == 1;
1520 my @dims = map $_->dims, @_;
1521 my @out;
1522 for my $ind (0..$#_) {
1523 push @out, $_[$ind]->slice(join ',', map $_==$ind ? '' : "*$dims[$_]", 0..$#_);
1524 }
1525 @out;
1526 }
1527 #line 1528 "lib/PDL/Slices.pm"
1528  
1529  
1530 =head2 lags
1531  
1532 =for sig
1533  
1534 Signature: (PARENT(); [oca]CHILD(); PDL_Indx nthdim;PDL_Indx step;PDL_Indx nlags)
1535 Types: (sbyte byte short ushort long ulong indx ulonglong longlong
1536 float double ldouble cfloat cdouble cldouble)
1537  
1538 =for usage
1539  
1540 $CHILD = lags($PARENT, $nthdim, $step, $nlags);
1541 $CHILD = $PARENT->lags($nthdim, $step, $nlags); # method call
1542 $PARENT->lags($nthdim, $step, $nlags) .= $data; # usable as lvalue
1543  
1544 =for ref
1545  
1546 Returns an ndarray of lags to parent.
1547  
1548 Usage:
1549  
1550 I.e. if C<$x> contains
1551  
1552 [0,1,2,3,4,5,6,7]
1553  
1554 then
1555  
1556 =for example
1557  
1558 $y = $x->lags(0,2,2);
1559  
1560 is a (6,2) matrix
1561  
1562 [2,3,4,5,6,7]
1563 [0,1,2,3,4,5]
1564  
1565 This order of returned indices is kept because the function is
1566 called "lags" i.e. the nth lag is n steps behind the original.
1567  
1568 C<$step> and C<$nlags> must be positive. C<$nthdim> can be
1569 negative and will then be counted from the last dim backwards
1570 in the usual way (-1 = last dim).
1571  
1572 =pod
1573  
1574 Does not broadcast.
1575 Makes L<virtual affine|PDL::Indexing> ndarrays.
1576 Creates data-flow back and forth by default.
1577  
1578 =for bad
1579  
1580 C<lags> does not process bad values.
1581 It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
1582  
1583 =cut
1584  
1585  
1586  
1587  
1588 *lags = \&PDL::lags;
1589  
1590  
1591  
1592  
1593  
1594  
1595 =head2 splitdim
1596  
1597 =for sig
1598  
1599 Signature: (PARENT(); [oca]CHILD(); PDL_Indx nthdim;PDL_Indx nsp)
1600 Types: (sbyte byte short ushort long ulong indx ulonglong longlong
1601 float double ldouble cfloat cdouble cldouble)
1602  
1603 =for usage
1604  
1605 $CHILD = splitdim($PARENT, $nthdim, $nsp);
1606 $CHILD = $PARENT->splitdim($nthdim, $nsp); # method call
1607 $PARENT->splitdim($nthdim, $nsp) .= $data; # usable as lvalue
1608  
1609 =for ref
1610  
1611 Splits a dimension in the parent ndarray (opposite of L<clump|PDL::Core/clump>).
1612 As of 2.076, throws exception if non-divisible C<nsp> given, and can
1613 give negative C<nthdim> which then counts backwards.
1614  
1615 =for example
1616  
1617 After
1618  
1619 $y = $x->splitdim(2,3);
1620  
1621 the expression
1622  
1623 $y->at(6,4,m,n,3,6) == $x->at(6,4,m+3*n)
1624  
1625 is always true (C<m> has to be less than 3).
1626  
1627 =pod
1628  
1629 Does not broadcast.
1630 Makes L<virtual affine|PDL::Indexing> ndarrays.
1631 Creates data-flow back and forth by default.
1632  
1633 =for bad
1634  
1635 C<splitdim> does not process bad values.
1636 It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
1637  
1638 =cut
1639  
1640  
1641  
1642  
1643 *splitdim = \&PDL::splitdim;
1644  
1645  
1646  
1647  
1648  
1649  
1650 =head2 rotate
1651  
1652 =for sig
1653  
1654 Signature: (x(n); indx shift(); [oca]y(n))
1655 Types: (sbyte byte short ushort long ulong indx ulonglong longlong
1656 float double ldouble cfloat cdouble cldouble)
1657  
1658 =for usage
1659  
1660 $y = rotate($x, $shift);
1661 $y = $x->rotate($shift); # method call
1662 $x->rotate($shift) .= $data; # usable as lvalue
1663  
1664 =for ref
1665  
1666 Shift vector elements along with wrap.
1667  
1668 =pod
1669  
1670 Broadcasts over its inputs.
1671 Creates data-flow back and forth by default.
1672  
1673 =for bad
1674  
1675 C<rotate> does not process bad values.
1676 It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
1677  
1678 =cut
1679  
1680  
1681  
1682  
1683 *rotate = \&PDL::rotate;
1684  
1685  
1686  
1687  
1688  
1689  
1690 =head2 broadcastI
1691  
1692 =for sig
1693  
1694 Signature: (PARENT(); [oca]CHILD(); PDL_Indx id; PDL_Indx whichdims[])
1695 Types: (sbyte byte short ushort long ulong indx ulonglong longlong
1696 float double ldouble cfloat cdouble cldouble)
1697  
1698 =for usage
1699  
1700 $CHILD = broadcastI($PARENT, $id, $whichdims);
1701 $CHILD = $PARENT->broadcastI($id, $whichdims); # method call
1702 $PARENT->broadcastI($id, $whichdims) .= $data; # usable as lvalue
1703  
1704 =for ref
1705  
1706 internal
1707  
1708 Put some dimensions to a broadcastid.
1709  
1710 =for example
1711  
1712 $y = $x->broadcastI(0,1,5); # broadcast over dims 1,5 in id 1
1713  
1714 =pod
1715  
1716 Does not broadcast.
1717 Makes L<virtual affine|PDL::Indexing> ndarrays.
1718 Creates data-flow back and forth by default.
1719  
1720 =for bad
1721  
1722 C<broadcastI> does not process bad values.
1723 It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
1724  
1725 =cut
1726  
1727  
1728  
1729  
1730 *broadcastI = \&PDL::broadcastI;
1731  
1732  
1733  
1734  
1735  
1736  
1737 =head2 unbroadcast
1738  
1739 =for sig
1740  
1741 Signature: (PARENT(); [oca]CHILD(); PDL_Indx atind)
1742 Types: (sbyte byte short ushort long ulong indx ulonglong longlong
1743 float double ldouble cfloat cdouble cldouble)
1744  
1745 =for usage
1746  
1747 $CHILD = unbroadcast($PARENT, $atind);
1748 $CHILD = $PARENT->unbroadcast($atind); # method call
1749 $PARENT->unbroadcast($atind) .= $data; # usable as lvalue
1750  
1751 =for ref
1752  
1753 All broadcasted dimensions are made real again.
1754  
1755 See [TBD Doc] for details and examples.
1756  
1757 =pod
1758  
1759 Does not broadcast.
1760 Makes L<virtual affine|PDL::Indexing> ndarrays.
1761 Creates data-flow back and forth by default.
1762  
1763 =for bad
1764  
1765 C<unbroadcast> does not process bad values.
1766 It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
1767  
1768 =cut
1769  
1770  
1771  
1772  
1773 *unbroadcast = \&PDL::unbroadcast;
1774  
1775  
1776  
1777  
1778  
1779 #line 1934 "lib/PDL/Slices.pd"
1780  
1781 =head2 dice
1782  
1783 =for ref
1784  
1785 Dice rows/columns/planes out of a PDL using indexes for
1786 each dimension.
1787  
1788 This function can be used to extract irregular subsets
1789 along many dimension of a PDL, e.g. only certain rows in an image,
1790 or planes in a cube. This can of course be done with
1791 the usual dimension tricks but this saves having to
1792 figure it out each time!
1793  
1794 This method is similar in functionality to the L</slice>
1795 method, but L</slice> requires that contiguous ranges or ranges
1796 with constant offset be extracted. ( i.e. L</slice> requires
1797 ranges of the form C<1,2,3,4,5> or C<2,4,6,8,10>). Because of this
1798 restriction, L</slice> is more memory efficient and slightly faster
1799 than dice
1800  
1801 =for usage
1802  
1803 $slice = $data->dice([0,2,6],[2,1,6]); # Dicing a 2-D array
1804  
1805 The arguments to dice are arrays (or 1D PDLs) for each dimension
1806 in the PDL. These arrays are used as indexes to which rows/columns/cubes,etc
1807 to dice-out (or extract) from the C<$data> PDL.
1808  
1809 Use C<X> to select all indices along a given dimension (compare also
1810 L<mslice|PDL::Core/mslice>). As usual (in slicing methods) trailing
1811 dimensions can be omitted implying C<X>'es for those.
1812  
1813 =for example
1814  
1815 pdl> $x = sequence(10,4)
1816 pdl> p $x
1817 [
1818 [ 0 1 2 3 4 5 6 7 8 9]
1819 [10 11 12 13 14 15 16 17 18 19]
1820 [20 21 22 23 24 25 26 27 28 29]
1821 [30 31 32 33 34 35 36 37 38 39]
1822 ]
1823 pdl> p $x->dice([1,2],[0,3]) # Select columns 1,2 and rows 0,3
1824 [
1825 [ 1 2]
1826 [31 32]
1827 ]
1828 pdl> p $x->dice(X,[0,3])
1829 [
1830 [ 0 1 2 3 4 5 6 7 8 9]
1831 [30 31 32 33 34 35 36 37 38 39]
1832 ]
1833 pdl> p $x->dice([0,2,5])
1834 [
1835 [ 0 2 5]
1836 [10 12 15]
1837 [20 22 25]
1838 [30 32 35]
1839 ]
1840  
1841 As this is an index function, any modifications to the
1842 slice will change the parent (use the C<.=> operator).
1843  
1844 =cut
1845  
1846 sub PDL::dice :lvalue {
1847  
1848 my $self = shift;
1849 my @dim_indexes = @_; # array of dimension indexes
1850  
1851 # Check that the number of dim indexes <=
1852 # number of dimensions in the PDL
1853 my $no_indexes = scalar(@dim_indexes);
1854 my $noDims = $self->getndims;
1855 barf("PDL::dice: Number of index arrays ($no_indexes) not equal to the dimensions of the PDL ($noDims")
1856 if $no_indexes > $noDims;
1857 my $index;
1858 my $pdlIndex;
1859 my $outputPDL=$self;
1860 my $indexNo = 0;
1861  
1862 # Go thru each index array and dice the input PDL:
1863 foreach $index(@dim_indexes){
1864 $outputPDL = $outputPDL->dice_axis($indexNo,$index)
1865 unless !ref $index && $index eq 'X';
1866  
1867 $indexNo++;
1868 }
1869  
1870 return $outputPDL;
1871 }
1872 *dice = \&PDL::dice;
1873  
1874 =head2 dice_axis
1875  
1876 =for ref
1877  
1878 Dice rows/columns/planes from a single PDL axis (dimension)
1879 using index along a specified axis
1880  
1881 This function can be used to extract irregular subsets
1882 along any dimension, e.g. only certain rows in an image,
1883 or planes in a cube. This can of course be done with
1884 the usual dimension tricks but this saves having to
1885 figure it out each time!
1886  
1887 =for usage
1888  
1889 $slice = $data->dice_axis($axis,$index);
1890  
1891 =for example
1892  
1893 pdl> $x = sequence(10,4)
1894 pdl> $idx = pdl(1,2)
1895 pdl> p $x->dice_axis(0,$idx) # Select columns
1896 [
1897 [ 1 2]
1898 [11 12]
1899 [21 22]
1900 [31 32]
1901 ]
1902 pdl> $t = $x->dice_axis(1,$idx) # Select rows
1903 pdl> $t.=0
1904 pdl> p $x
1905 [
1906 [ 0 1 2 3 4 5 6 7 8 9]
1907 [ 0 0 0 0 0 0 0 0 0 0]
1908 [ 0 0 0 0 0 0 0 0 0 0]
1909 [30 31 32 33 34 35 36 37 38 39]
1910 ]
1911  
1912 The trick to using this is that the index selects
1913 elements along the dimensions specified, so if you
1914 have a 2D image C<axis=0> will select certain C<X> values
1915 - i.e. extract columns
1916  
1917 As this is an index function, any modifications to the
1918 slice will change the parent.
1919  
1920 =cut
1921  
1922 sub PDL::dice_axis :lvalue {
1923 my($self,$axis,$idx) = @_;
1924 my $ix = PDL->topdl($idx);
1925 barf("dice_axis: index must be <=1D") if $ix->getndims > 1;
1926 return $self->mv($axis,0)->index1d($ix)->mv(0,$axis);
1927 }
1928 *dice_axis = \&PDL::dice_axis;
1929 #line 1930 "lib/PDL/Slices.pm"
1930  
1931  
1932 =head2 slice
1933  
1934 =for sig
1935  
1936 Signature: (PARENT(); [oca]CHILD(); pdl_slice_args *arglist)
1937 Types: (sbyte byte short ushort long ulong indx ulonglong longlong
1938 float double ldouble cfloat cdouble cldouble)
1939  
1940 =for usage
1941  
1942 $CHILD = slice($PARENT, $arglist);
1943 $CHILD = $PARENT->slice($arglist); # method call
1944 $PARENT->slice($arglist) .= $data; # usable as lvalue
1945  
1946 =for example
1947  
1948 $slice = $data->slice([2,3],'x',[2,2,0],"-1:1:-1", "*3");
1949  
1950 =for ref
1951  
1952 Extract rectangular slices of an ndarray, from a string specifier,
1953 an array ref specifier, or a combination.
1954  
1955 C<slice> is the main method for extracting regions of PDLs and
1956 manipulating their dimensionality. You can call it directly or
1957 via the L<NiceSlice|PDL::NiceSlice> source prefilter that extends
1958 Perl syntax to include array slicing.
1959  
1960 C<slice> can extract regions along each dimension of a source PDL,
1961 subsample or reverse those regions, dice each dimension by selecting a
1962 list of locations along it, or basic PDL indexing routine. The
1963 selected subfield remains connected to the original PDL via dataflow.
1964 In most cases this neither allocates more memory nor slows down
1965 subsequent operations on either of the two connected PDLs.
1966  
1967 You pass in a list of arguments. Each term in the list controls
1968 the disposition of one axis of the source PDL and/or returned PDL.
1969 Each term can be a string-format cut specifier, a list ref that
1970 gives the same information without recourse to string manipulation,
1971 or a PDL with up to 1 dimension giving indices along that axis that
1972 should be selected.
1973  
1974 If you want to pass in a single string specifier for the entire
1975 operation, you can pass in a comma-delimited list as the first
1976 argument. C<slice> detects this condition and splits the string
1977 into a regular argument list. This calling style is fully
1978 backwards compatible with C<slice> calls from before PDL 2.006.
1979  
1980 B<STRING SYNTAX>
1981  
1982 If a particular argument to C<slice> is a string, it is parsed as a
1983 selection, an affine slice, or a dummy dimension depending on the
1984 form. Leading or trailing whitespace in any part of each specifier is
1985 ignored (though it is not ignored within numbers).
1986  
1987 =over 3
1988  
1989 =item C<< '' >>, C<< : >>, or C<< X >> -- keep
1990  
1991 The empty string, C<:>, or C<X> cause the entire corresponding
1992 dimension to be kept unchanged.
1993  
1994 =item C<< <n> >> -- selection
1995  
1996 A single number alone causes a single index to be selected from the
1997 corresponding dimension. The dimension is kept (and reduced to size
1998 1) in the output.
1999  
2000 =item C<< (<n>) >> -- selection and collapse
2001  
2002 A single number in parenthesis causes a single index to be selected
2003 from the corresponding dimension. The dimension is discarded
2004 (completely eliminated) in the output.
2005  
2006 =item C<< <n>:<m> >> -- select an inclusive range
2007  
2008 Two numbers separated by a colon selects a range of values from the
2009 corresponding axis, e.g. C<< 3:4 >> selects elements 3 and 4 along the
2010 corresponding axis, and reduces that axis to size 2 in the output.
2011 Both numbers are regularized so that you can address the last element
2012 of the axis with an index of C< -1 >. If, after regularization, the
2013 two numbers are the same, then exactly one element gets selected (just
2014 like the C<< <n> >> case). If, after regulariation, the second number
2015 is lower than the first, then the resulting slice counts down rather
2016 than up -- e.g. C<-1:0> will return the entire axis, in reversed
2017 order.
2018  
2019 =item C<< <n>:<m>:<s> >> -- select a range with explicit step
2020  
2021 If you include a third parameter, it is the stride of the extracted
2022 range. For example, C<< 0:-1:2 >> will sample every other element
2023 across the complete dimension. Specifying a stride of 1 prevents
2024 autoreversal -- so to ensure that your slice is *always* forward
2025 you can specify, e.g., C<< 2:$n:1 >>. In that case, an "impossible"
2026 slice gets an Empty PDL (with 0 elements along the corresponding
2027 dimension), so you can generate an Empty PDL with a slice of the
2028 form C<< 2:1:1 >>.
2029  
2030 =item C<< *<n> >> -- insert a dummy dimension
2031  
2032 Dummy dimensions aren't present in the original source and are
2033 "mocked up" to match dimensional slots, by repeating the data
2034 in the original PDL some number of times. An asterisk followed
2035 by a number produces a dummy dimension in the output, for
2036 example C<< *2 >> will generate a dimension of size 2 at
2037 the corresponding location in the output dim list. Omitting
2038 the number (and using just an asterisk) inserts a dummy dimension
2039 of size 1.
2040  
2041 =back
2042  
2043 B<ARRAY REF SYNTAX>
2044  
2045 If you feed in an ARRAY ref as a slice term, then it can have
2046 0-3 elements. The first element is the start of the slice along
2047 the corresponding dim; the second is the end; and the third is
2048 the stepsize. Different combinations of inputs give the same
2049 flexibility as the string syntax.
2050  
2051 =over 3
2052  
2053 =item C<< [] >> - keep dim intact
2054  
2055 An empty ARRAY ref keeps the entire corresponding dim
2056  
2057 =item C<< [ 'X' ] >> - keep dim intact
2058  
2059 =item C<< [ '*',$n ] >> - generate a dummy dim of size $n
2060  
2061 If $n is missing, you get a dummy dim of size 1.
2062  
2063 =item C<< [ $dex, 0, 0 ] >> - collapse and discard dim
2064  
2065 C<$dex> must be a single value. It is used to index
2066 the source, and the corresponding dimension is discarded.
2067  
2068 =item C<< [ $start, $end ] >> - collect inclusive slice
2069  
2070 In the simple two-number case, you get a slice that runs
2071 up or down (as appropriate) to connect $start and $end.
2072  
2073 =item C<< [ $start, $end, $inc ] >> - collect inclusive slice
2074  
2075 The three-number case works exactly like the three-number
2076 string case above.
2077  
2078 =back
2079  
2080 B<PDL args for dicing>
2081  
2082 If you pass in a 0- or 1-D PDL as a slicing argument, the
2083 corresponding dimension is "diced" -- you get one position
2084 along the corresponding dim, per element of the indexing PDL,
2085 e.g. C<< $x->slice( pdl(3,4,9)) >> gives you elements 3, 4, and
2086 9 along the 0 dim of C<< $x >>.
2087  
2088 Because dicing is not an affine transformation, it is slower than
2089 direct slicing even though the syntax is convenient.
2090  
2091 =for example
2092  
2093 $x->slice('1:3'); # return the second to fourth elements of $x
2094 $x->slice('3:1'); # reverse the above
2095 $x->slice('-2:1'); # return last-but-one to second elements of $x
2096  
2097 $x->slice([1,3]); # Same as above three calls, but using array ref syntax
2098 $x->slice([3,1]);
2099 $x->slice([-2,1]);
2100  
2101 =pod
2102  
2103 Does not broadcast.
2104 Makes L<virtual affine|PDL::Indexing> ndarrays.
2105 Creates data-flow back and forth by default.
2106  
2107 =for bad
2108  
2109 C<slice> does not process bad values.
2110 It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
2111  
2112 =cut
2113  
2114  
2115  
2116  
2117  
2118 #line 2252 "lib/PDL/Slices.pd"
2119 sub PDL::slice :lvalue {
2120 my ($source, @others) = @_;
2121 for my $i(0..$#others) {
2122 my $idx = $others[$i];
2123 if (ref $idx eq 'ARRAY') {
2124 my @arr = map UNIVERSAL::isa($_, 'PDL') ? $_->flat->at(0) : $_, @{$others[$i]};
2125 $others[$i] = \@arr;
2126 next;
2127 }
2128 next if !( blessed($idx) && $idx->isa('PDL') );
2129 # Deal with dicing. This is lame and slow compared to the
2130 # faster slicing, but works okay. We loop over each argument,
2131 # and if it's a PDL we dispatch it in the most straightforward
2132 # way. Single-element and zero-element PDLs are trivial and get
2133 # converted into slices for faster handling later.
2134 barf("slice: dicing parameters must be at most 1D (arg $i)\n")
2135 if $idx->ndims > 1;
2136 my $nlm = $idx->nelem;
2137 if($nlm > 1) {
2138 #### More than one element - we have to dice (darn it).
2139 $source = $source->mv($i,0)->index1d($idx)->mv(0,$i);
2140 $others[$i] = '';
2141 }
2142 elsif($nlm) {
2143 #### One element - convert to a regular slice.
2144 $others[$i] = $idx->flat->at(0);
2145 }
2146 else {
2147 #### Zero elements -- force an extended empty.
2148 $others[$i] = "1:0:1";
2149 }
2150 }
2151 PDL::_slice_int($source,my $o=$source->initialize,\@others);
2152 $o;
2153 }
2154 #line 2155 "lib/PDL/Slices.pm"
2155  
2156 *slice = \&PDL::slice;
2157  
2158  
2159  
2160  
2161  
2162  
2163 =head2 diagonal
2164  
2165 =for sig
2166  
2167 Signature: (PARENT(); [oca]CHILD(); PDL_Indx whichdims[])
2168 Types: (sbyte byte short ushort long ulong indx ulonglong longlong
2169 float double ldouble cfloat cdouble cldouble)
2170  
2171 =for ref
2172  
2173 Returns the multidimensional diagonal over the specified dimensions.
2174  
2175 The diagonal is placed at the first (by number) dimension that is
2176 diagonalized.
2177 The other diagonalized dimensions are removed. So if C<$x> has dimensions
2178 C<(5,3,5,4,6,5)> then after
2179  
2180 =for usage
2181  
2182 $d = $x->diagonal(dim1, dim2,...)
2183  
2184 =for example
2185  
2186 $y = $x->diagonal(0,2,5);
2187  
2188 the ndarray C<$y> has dimensions C<(5,3,4,6)> and
2189 C<$y-E<gt>at(2,1,0,1)> refers
2190 to C<$x-E<gt>at(2,1,2,0,1,2)>.
2191  
2192 NOTE: diagonal doesn't handle broadcastids correctly. XXX FIX
2193  
2194 pdl> $x = zeroes(3,3,3);
2195 pdl> ($y = $x->diagonal(0,1))++;
2196 pdl> p $x
2197 [
2198 [
2199 [1 0 0]
2200 [0 1 0]
2201 [0 0 1]
2202 ]
2203 [
2204 [1 0 0]
2205 [0 1 0]
2206 [0 0 1]
2207 ]
2208 [
2209 [1 0 0]
2210 [0 1 0]
2211 [0 0 1]
2212 ]
2213 ]
2214  
2215 =pod
2216  
2217 Does not broadcast.
2218 Makes L<virtual affine|PDL::Indexing> ndarrays.
2219 Creates data-flow back and forth by default.
2220  
2221 =for bad
2222  
2223 C<diagonal> does not process bad values.
2224 It will set the bad-value flag of all output ndarrays if the flag is set for any of the input ndarrays.
2225  
2226 =cut
2227  
2228  
2229  
2230  
2231  
2232 #line 2466 "lib/PDL/Slices.pd"
2233 sub PDL::diagonal :lvalue { shift->_diagonal_int(my $o=PDL->null, \@_); $o }
2234 #line 2235 "lib/PDL/Slices.pm"
2235  
2236 *diagonal = \&PDL::diagonal;
2237  
2238  
2239  
2240  
2241  
2242  
2243  
2244 #line 2516 "lib/PDL/Slices.pd"
2245  
2246 =head1 BUGS
2247  
2248 For the moment, you can't slice one of the zero-length dims of an
2249 empty ndarray. It is not clear how to implement this in a way that makes
2250 sense.
2251  
2252 Many types of index errors are reported far from the indexing
2253 operation that caused them. This is caused by the underlying architecture:
2254 slice() sets up a mapping between variables, but that mapping isn't
2255 tested for correctness until it is used (potentially much later).
2256  
2257 =head1 AUTHOR
2258  
2259 Copyright (C) 1997 Tuomas J. Lukka. Contributions by
2260 Craig DeForest, deforest@boulder.swri.edu.
2261 Documentation contributions by David Mertens.
2262 All rights reserved. There is no warranty. You are allowed
2263 to redistribute this software / documentation under certain
2264 conditions. For details, see the file COPYING in the PDL
2265 distribution. If this file is separated from the PDL distribution,
2266 the copyright notice should be included in the file.
2267  
2268 =cut
2269 #line 2270 "lib/PDL/Slices.pm"
2270  
2271 # Exit with OK status
2272  
2273 1;
« lib/PDL/Primitive.pm ↑ Summary lib/PDL/Ufunc.pm »