resize_matrix trim or/and extend (and cast) a matrix or hypermatrix

## Syntax

                resize_matrix   // demo

                resMat = resize_matrix(mat, nbRows, nbCols)
                resMat = resize_matrix(mat, nbRows, nbCols, resType)
                resMat = resize_matrix(mat, nbRows, nbCols, resType, padding)
                resMat = resize_matrix(mat, nbRows, nbCols,    ""  , padding)

                resMat = resize_matrix(mat, newSizes)
                resMat = resize_matrix(mat, newSizes, resType)
                resMat = resize_matrix(mat, newSizes, resType, padding)
                resMat = resize_matrix(mat, newSizes,    ""  , padding)

## Arguments

mat

  input matrix or hypermatrix. booleans, encoded integers, decimal-encoded numbers (real or complex), polynomials, or text are supported.

nbRows

  new number of rows of the resized matrix. Exceeding rows are trimmed. Missing rows are added by padding. Setting `nbRows < 0` keeps the current number of rows.

nbCols

  new number of columns of the resized matrix. Exceeding columns are trimmed. Missing columns are added by padding. Setting `nbCols < 0` keeps the current number of columns.

newSizes

  vector specifying the new sizes along each dimension of `mat`. To keep a new size equal to the current one, just set it to -1.

  If the vector `newSizes` is shorter than `size(mat)`, it is padded with ones. Example: if `mat` with `size(mat)==[ 4 3 3 2]` is provided and `newSizes=[6 2]` is specified, `newSizes = [6 2 1 1]` is considered.

  Conversely, if `newSizes` is longer than `size(mat)`, new dimensions are added to `mat` and padded. Example: if `mat` such that `size(mat)==[ 4 3 ]` is provided and `newSizes=[6 2 2]` is specified, the result will be an hypermatrix with 2 pages, the second one being fully padded.

  `newSizes = [nbRows, nbCols]` may be used for a matrix.

padding

  optional scalar of same type as `mat`, specifying the content to set in elements created when the size along a dimension is increased. The default padding is done with `0` (real or complex decimals, encoded integers, polynomials), or `""` (text), or `%F` (booleans).

  When `mat` and `padding` types do not match, scilab tries to convert the `padding`'s one

  For polynomials, the varname of the padding is forced to the `mat`'s one.

resType

  optional text word specifying the data type into which the resized matrix must be converted. "boolean", "constant", "string", "int8", "uint8", "int16", "uint16", "int32", "uint32", "int64", and "uint64" are supported.

  Type conversion is supported neither for Polynomials nor for hypermatrix of text.

resMat

  resized (and converted) matrix or hypermatrix

## Description

Creates a matrix of sizes `[nbRows, nbCols]` or `newSizes`, or an hypermatrix of sizes `newSizes`. If for a dimension the new size is smaller than the initial one, the matrix is cropped. If the size is increased, the matrix/hypermatrix is padded. The number of dimensions can be increased. Conversely, Scilab automatically squeezes highest dimensions with size kept or set to 1 (singletons).

The type of the result may be changed by specifying the `resType` argument, with restrictions given above.

## Examples

    // Embedded examples, including with polynomials:
    //resize_matrix

    // Resizing a numerical matrix:
    M = grand(4, 3, "uin", -9, 9)
    resize_matrix(M, -1, 5)  //  use -1 to keep a size unchanged
    resize_matrix(M, 2, -1)
    resize_matrix(M, 3, 4)

    --> M = grand(4, 3, "uin", -9, 9)
     M  =
      -8.  -5.  -2.
      -9.   0.  -1.
       4.  -1.   6.
       5.   1.   8.

    --> resize_matrix(M, -1, 5)  //  use -1 to keep a size unchanged
     ans  =
      -8.  -5.  -2.   0.   0.
      -9.   0.  -1.   0.   0.
       4.  -1.   6.   0.   0.
       5.   1.   8.   0.   0.

    --> resize_matrix(M, 2, -1)
     ans  =
      -8.  -5.  -2.
      -9.   0.  -1.

    --> resize_matrix(M, 3, 4)
     ans  =
      -8.  -5.  -2.   0.
      -9.   0.  -1.   0.
       4.  -1.   6.   0.

    M = grand(4, 3, "uin", -9, 9)
    resize_matrix(M, [3 4 2])
    resize_matrix(M, [3 4 2], "", %i)
    resize_matrix(M, [3 4 2], "string", %i)

    // Matrix of text:
    myMatString = ["Scilab", "the"; "Open Source", "Scientific"; "Software", "Package"]
    resize_matrix( myMatString, 5, 3 )
    // Equivalent syntax for new sizes:
    resize_matrix( myMatString, [5 3], "", "$" )    // With custom padding

    // Crops, pads and casts an hypermatrix:
    h = rand(2, 3, 2)*200
    resize_matrix(h, [3 2 3], "int8")
    resize_matrix(h, [3 2 3], "int8", -1)    // Custom padding
    r = resize_matrix(h, [3 2 ] , "" , -1)   // Custom padding without type conversion
    size(r)  // The last dimension has been squeezed

    // With Polynomials:
    x = poly(0, "x");
    P = (1-x)^grand(4, 2, "uin", 0, 3)
    resize_matrix(P, 3, 3)
    resize_matrix(P, [3 3 2])
    resize_matrix(P, [3 3 2], "", %z)
    //  => The padding's unknown is forced to the P's one
    //  => Polynomials can't be converted

## See also

- matrix
- size
- typeof
- double
- strtod
- string

## History

5.5.0

- Polynomials and Hypermatrices are now accepted.
- A custom padding can now be provided.
- New sizes can be specified in a vector.
- resize_matrix() with no parameters displays examples (demo).

6.0.1 The `resType` option is extended to the new `int64` and `uint64` integer types.