develooper Front page | | Postings from September 2000

RFC 148 (v3) Arrays: Add reshape() for multi-dimensional array reshaping

Perl6 RFC Librarian
September 21, 2000 13:13
RFC 148 (v3) Arrays: Add reshape() for multi-dimensional array reshaping
Message ID:
=head1 VERSION

This and other RFCs are available on the web at

=head1 TITLE

Arrays: Add reshape() for multi-dimensional array reshaping
=head1 VERSION

  Maintainer: Jeremy Howard <>
  Date: 24 Aug 2000
  Last Modified: 21 Sep 2000
  Mailing List:
  Number: 148
  Version: 3
  Status: Frozen

=head1 CHANGES

Changed semantics to match PDL, NumPy, and J. Changed maintainer from
Nathan Wiger <>.


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 C<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);          # ([1],[2],[3],[4],[5],[6])
  @d = reshape([6,1], @a);          # (1,2,3,4,5,6)
  @e = reshape([1,2,3], @a);        # ([[1],[2]],[[3],[4]],[[5],[6]])
The dimensions specified in the first argument are the same ones used by
the C<:shape> array attribute described in L<RFC 203>. L<RFC 202> gives
an overview of the proposed multidimensional arrays that C<reshape>
works with.

We only need one C<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:

=over 4

=item 1

Less data than specified causes C<reshape> to repeat the data as many
times as necessary to fill the new structure (like C<$> in the J language)

=item 2

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 C<reshape> match those of PDL's reshape(), NumPy's
reshape(), and J's verb C<$>. See the references.

C<reshape> creates an alias to the original array, not a copy (this is
like merge/demerge/part/flatten). See L<RFC 90> for discussion of aliasing
behaviour that would apply to C<reshape>.


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
operation. However, C<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

reshape() in NumPy:

reshape() in PDL: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About