areshape
==============================================

Purpose
----------------
Reshapes a scalar, matrix, or array into an array of user-specified size.

Format
----------------
.. function:: y = areshape(x, orders)

    :param x:
    :type x: scalar or matrix or N-dimensional array.

    :param orders: orders. the sizes of the dimensions of the new array.
    :type orders: Mx1 vector

    :return y: created from data in *x*.

    :rtype y: M-dimensional array

Examples
----------------

::

    x = 3;
    orders = { 2, 3, 4 };
    y = areshape(x, orders);

*y* will be a 2x3x4 array of threes.

::

    // Create a 30x3 matrix with consecutive integer values
    x = reshape(seqa(1, 1, 90), 30, 3);

    orders = { 2, 3, 4, 5 };
    y = areshape(x, orders);

*y* will be a 2x3x4x5 array. Since *y* contains 120 elements and *x* contains only 90, the first 90 elements of *y* will be set to the sequence of integers from 1 to 90 that are contained in *x*, and the last 30 elements of *y* will
be set to the sequence of integers from 1 to 30 contained in the first 30 elements of *x*.

::

    // Create a 20x3 matrix with consecutive integer values
    x = reshape(seqa(1, 1, 60), 20, 3);

    orders = { 3, 2, 4 };
    y = areshape(x, orders);

*y* will be a 3x2x4 array. Since *y* contains 24 elements, and *x* contains 60, the elements of *y* will be set to the sequence of integers from 1 to 24 contained in the first 24 elements of *x*.

Remarks
-------

If there are more elements in *x* than in *y*, the remaining elements are
discarded. If there are not enough elements in *x* to fill *y*, then when
:func:`areshape` runs out of elements, it goes back to the first element of *x*
and starts getting additional elements from there.

.. seealso:: Functions :func:`aconcat`, :func:`squeeze`