[% setvar title Arrays: Add reshape() for multi-dimensional array reshaping %]
|Note: these documents may be out of date. Do not use as reference!|
To see what is currently happening visit http://www.perl6.org/
Arrays: Add reshape() for multi-dimensional array reshaping
Maintainer: Jeremy Howard <firstname.lastname@example.org> Date: 24 Aug 2000 Last Modified: 21 Sep 2000 Mailing List: email@example.com Number: 148 Version: 3 Status: Frozen
Changed semantics to match PDL, NumPy, and J. Changed maintainer from Nathan Wiger <firstname.lastname@example.org>.
Currently, there is no easy way to reshape existing arrays into multiple arrays or matrices. This makes nifty array manipulation and complex math hard.
A general-purpose tool that can do arbitrary multi-dimensional array reshaping, from which other array manipulation functions can be derived, makes data manipulation easier.
Let's jump in. This RFC proposes a
reshape builtin that takes an array
to reshape as the second parameter, and a list of dimensions to reshape
the array to as the first parameter:
my int @a = ([1,2,3], [4,5,6]); @b = reshape([2,3], @a); # ([1,2],[3,4],[5,6]) @c = reshape([1,6], @a); # (,,,,,) @d = reshape([6,1], @a); # (1,2,3,4,5,6) @e = reshape([1,2,3], @a); # ([,],[,],[,])
The dimensions specified in the first argument are the same ones used by
:shape array attribute described in "RFC 203". "RFC 202" gives
an overview of the proposed multidimensional arrays that
We only need one
reshape since it is a multipurpose tool that works in
any direction, serving as its own inverse.
The dimensions used are subject to the following properties:
Less data than specified causes
reshape to repeat the data as many
times as necessary to fill the new structure (like
$ in the J language)
More data than specified is silently discarded
Any one (but no more than one) element of the list of dimensions can be '-1', which indicates that that dimension should be made as large as necessary to fill in the array:
my int @a = ([1,2,3], [4,5,6]); @b = reshape([-1,3], @a); # ([1,2],[3,4],[5,6]) @c = reshape([-1], @a); # (1,2,3,4,5,6)
The semantics of
reshape match those of PDL's reshape(), NumPy's
reshape(), and J's verb
$. See the references.
reshape creates an alias to the original array, not a copy (this is
like merge/demerge/part/flatten). See "RFC 90" for discussion of aliasing
behaviour that would apply to
For simple typed arrays (RFC 203) it is simply a case of changing the
dimension attributes stored internally. For standard lists of lists, the
actual references and arrays will have to be rejigged, with will be a slow
reshape should rarely be used on arrays that are
not stored compactly, since standard lists of lists are unlikely to be
used for heavy data crunching.
None. This introduces new functionality.
RFC 81: Lazily evaluated list generation functions
RFC 90: Arrays: Builtins: merge() and demerge()
RFC 202: Arrays: Overview of multidimensional array RFCs (RFC 203 through RFC 207)
RFC 203: Arrays: Notation for declaring and creating arrays
Thanks to Uri Guttman for suggesting the APL "reshape" name
The '$' verb in J, described in The J Primer (provided as a help file with the J Language, available from www.jsoftware.com
reshape() in NumPy: starship.python.net#SEC3
reshape() in PDL: pdl.sourceforge.net#reshape