Procedure

   void xposeg_c ( const void   * matrix, 
                   SpiceInt       nrow, 
                   SpiceInt       ncol, 
                   void         * xposem ) 

Abstract

 
   Transpose a matrix of arbitrary size (in place, the matrix 
   need not be square). 
 

Required_Reading

 
   None. 
 

Keywords

 
   MATRIX 
 

Brief_I/O

 
   VARIABLE  I/O  DESCRIPTION 
   --------  ---  -------------------------------------------------- 
   matrix     I   Matrix to be transposed. 
   nrow       I   Number of rows of input matrix. 
   ncol       I   Number of columns of input matrix. 
   xposem     O   Transposed matrix (xposem can overwrite matrix). 
 

Detailed_Input

 
   matrix         Matrix to be transposed. 
 
   nrow           Number of rows of input matrix. 
 
   ncol           Number of columns of input matrix. 
 

Detailed_Output

 
   xposem         Transposed matrix.  xposem can overwrite matrix. 
 

Parameters

 
   None. 
 

Exceptions

 
   Error Free. 
 
   1) If either nrow or ncol is less than or equal to zero, no action 
      is taken. The routine simply returns. 
 

Files

 
   None. 
 

Particulars

 
   This routine transposes the input matrix and writes the 
   result to the matrix xposem.  This algorithm is performed in 
   such a way that the transpose can be performed in place.  That 
   is, matrix and xposem can use the same storage area in memory. 
 
   NOTE:  The matrices matrix and xposem are declared 
          one-dimensional for computational purposes only.  The 
          calling program should declare them as matrix[nrow][ncol]
          and xposem[ncol][nrow]. 
 
          This routine works on the assumption that the input and 
          output matrices are defined as described above.  More 
          specifically it assumes that the elements of the matrix 
          to be transformed is stored in contiguous memory locations 
          as shown here.  On output these elements will be 
          rearranged in consecutive memory locations as shown. 
 
 
             matrix                xposem
 
             m[0][0]               m[0][0]
             m[0][1]               m[1][0]
             m[0][2]               m[2][0]
             .                     .
             .                     .
             m[0][ncol-1]          .
             m[1][0]               m[nrow-1][0]
             m[1][1]               m[0][1]
             m[1][2]               m[1][1]
             .                     m[2][1]
             .                     .
             m[1][ncol-1]          .
             .                     .
                                   m[nrow-1][1]
             .                     .
 
             .                     .
 
             .                     .
                                   m[0][ncol-1]
             m[nrow-1][0]          m[1][ncol-1]
             m[nrow-1][1]          m[2][ncol-1]
             m[nrow-1][2]          .
             .                     .
             .                     .
             m[nrow-1][ncol-1]     m[nrow-1][ncol-1]
 
 
   For those familiar with permutations, this algorithm relies upon the
   fact that the transposition of a matrix, which has been stored as a
   string, is simply the action of a permutation applied to that
   string.  Since any permutation can be decomposed as a product of
   disjoint cycles, it is possible to transpose the matrix with only
   one additional storage register.  However, once a cycle has been
   computed it is necessary to find the next entry in the string that
   has not been moved by the permutation.  For this reason the
   algorithm is slower than would be necessary if the numbers of rows
   and columns were known in advance.
 

Examples

 
   This routine is primarily useful when attempting to transpose large
   matrices, where inplace transposition is important.  For example
   suppose you have the following declarations
 
      SpiceDouble           matrix [1003][800];
 
   If the transpose of the matrix is needed, it may not be possible to
   fit a second matrix requiring the same storage into memory.  Instead
   declare xposem as below so that no additional memory is allocated.
 
      SpiceDouble        (* xposem) [1003]  =  matrix;
        
   To obtain the transpose simply execute 
 
      xposeg_c ( matrix, 1003, 800, xposem ); 
 

Restrictions

 
   None. 
 

Literature_References

 
   None. 
 

Author_and_Institution

 
   N.J. Bachman    (JPL) 
   W.L. Taber      (JPL) 
 

Version

  
   -CSPICE Version 1.1.0, 24-JUL-2001   (NJB)

       Changed protoype:  input matrix is now type (const void *).
       Implemented interface macro for casting input matrix to const.

   -CSPICE Version 1.0.0, 31-MAY-1999 (NJB) (WLT)

Index_Entries

 
   transpose a matrix general 
 

Link to routine xposeg_c source file xposeg_c.c