Language Reference: CSHAPE Function

CSHAPE Function

CSHAPE( matrix, nrow, ncol, size <, padchar> ) ;

The CSHAPE function changes the shape of a character matrix by redefining the matrix dimensions.

The arguments to the CSHAPE function are as follows:

matrix: is a character matrix or quoted literal.
nrow: is the number of rows.
ncol: is the number of columns.
size: is the element length.
padchar: is an optional padding character.

The dimension of the matrix created by the CSHAPE function is specified by nrow (the number of rows), ncol (the number of columns), and size (the element length). A padding character is specified by padchar.

The CSHAPE function works by looking at the source matrix as if the characters of the source elements had been concatenated in row-major order. The source characters are then regrouped into elements of length size. These elements are assigned to the result matrix, once again in row-major order.

If there are not enough characters for the result matrix, the source of the remaining characters depends on whether padding was specified with padchar. If no padding was specified, the characters in the source matrix are cycled through again. If a padding character was specified, the remaining characters are all the padding character.

If one of the size arguments (nrow, ncol, or size) is zero, the CSHAPE function computes the dimension of the output matrix by dividing the number of elements of the input matrix by the product of the nonzero arguments.

For example, the following statement produces a $\text{[math]}$ matrix:

a = cshape("abcd", 2, 2, 1);
print a;

Figure 23.76 Reshaped Character Matrix

a
a	b
c	d

The following statement rearranges the 12 characters in the input matrix into a $\text{[math]}$ matrix with three characters in each element:

m = {"ab" "cd",
     "ef" "gh",
     "ij" "kl"};
b = cshape(m, 2, 2, 3);
print b;

Figure 23.77 Reshaped Character Matrix

b
abc	def
ghi	jkl

The following statement uses the size argument to specify the length of the result matrix. Notice that the characters in the matrix argument are reused in order to form a $\text{[math]}$ matrix with three characters in each element.

c = cshape("abcde", 2, 2, 3);
print c;

Figure 23.78 Reusing Characters

c
abc	dea
bcd	eab

The next example is similar, except that the optional padchar argument is used to specify what character to use after the characters in the matrix argument are each used once:

d = cshape("abcde", 2, 2, 3, "*");
print d;

Figure 23.79 Using a Pad Character

d
abc	de*
***	***

See also the description of the SHAPE function, which is used with numeric data.