xposeg_c

Index Page xposeg_c
A B C D E F G H I J K L M N O P Q R S T U V W X
Procedure Abstract Required_Reading Keywords Brief_I/O Detailed_Input | Detailed_Output Parameters Exceptions Files Particulars Examples | Restrictions Literature_References Author_and_Institution Version Index_Entries
#### 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

    Thu Apr 16 08:59:44 2009