Language Reference

CSHAPE Function

reshapes and repeats character values

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

The inputs 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 a padding character.

The CSHAPE function shapes character matrices. See also the description of the SHAPE function, which is used with numeric data.

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 source matrix's characters are cycled through again. If a padding character was specified, the remaining characters are all the padding character.

If one of the dimension arguments (nrow, ncol), or size) is zero, the 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 the matrix , as shown:

  
    r=cshape('abcd',2,2,1);
 

  
         R        2 rows      2 cols    (character, size 1) 
  
                              a b 
                              c d
 

The following statement produces a different matrix , as shown:

  
    r=cshape('a',1,2,3);
 

  
            R        1 row       2 cols    (character, size 3) 
  
                               aaa aaa
 

The following statement produces the matrix , as shown:

  
    r=cshape({'ab' 'cd', 
              'ef' 'gh', 
              'ij' 'kl'}, 2, 2, 3);
 

  
            R         2 rows      2 cols    (character, size 3) 
  
                               abc def 
                               ghi jkl
 

The following statement produces the matrix , as shown:

  
    r=cshape('XO',3,3,1);
 

  
            R          3 rows      3 cols    (character, size 1) 
  
                                  X O X 
                                  O X O 
                                  X O X
 

Finally, the following statement produces the matrix , as shown:

  
    r=cshape('abcd',2,2,3,'*');
 

  
            R           2 rows      2 cols    (character, size 3) 
  
                                  abc d** 
                                  *** ***