lib/PDL/Slices.pd

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