#########################################################################/**
 # @RdocFunction invertMap
 #
 # @title "Inverts a read or a write map"
 #
 # @synopsis 
 # 
 # \description{
 #   @get "title".
 # }
 # 
 # \arguments{
 #   \item{map}{An @integer @vector.}
 #   \item{...}{Not used.}
 # }
 # 
 # \value{
 #   Returns an @integer @vector.
 # }
 #
 # \details{
 #   An map is defined to be a @vector of \emph{n} with unique finite
 #   values in \eqn{[1,n]}.  Finding the inverse of a map is the same as 
 #   finding the rank of each element, cf. @see "base::order".  However,
 #   this method is much faster, because it utilizes the fact that all 
 #   values are unique and in \eqn{[1,n]}.  Moreover, for any map it holds
 #   that taking the inverse twice will result in the same map.
 # }
 #
 # @examples "../incl/invertMap.Rex"
 #

 # @author "HB"

 # 
 # \seealso{
 #   To generate an optimized write map for a CDF file, see 
 #   @see "readCdfUnitsWriteMap".
 # }
 # 
 # @keyword "file"
 # @keyword "IO"

 # @keyword "internal"

 #*/#########################################################################
 invertMap <- function(map, ...) {
   n <- length(map);
   if (n == 0)
     return(map);
 
   # Validate map
   r <- range(map);
   if (any(is.na(r))) {
     stop("Argument 'map' is not a map. It contains NA values.");
   }
   if (r[1] != 1 || r[2] != n) {
     stop("Argument 'map' is not a map. Its range is not [1,", n, "]: ",
                                                "[", r[1], ", ", r[2], "]");
   }
 
   # Create the inverse map
   inverseMap <- vector("integer", n);
   idx <- 1:n;
   inverseMap[.subset(map, idx)] <- idx;  # == inverseMap[map[idx]] <- idx;
 
   inverseMap;
 } # invertMap()
 
 
 ############################################################################
 # HISTORY:
 # 2006-03-30
 # o Created.
 ############################################################################