readCel <- function(filename,

                     indices = NULL,
                     readHeader = TRUE,

                     readXY = FALSE,

                     readIntensities = TRUE,

                     readStdvs = FALSE,

                     readPixels = FALSE,
                     readOutliers = TRUE,

                     readMasked = TRUE,
                     readMap = NULL,

                     verbose = 0,
                     .checkArgs = TRUE) {

     # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     # Local functions
     # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     qsort <- function(x) {
   ##    o0 <- .Internal(qsort(x, TRUE));
   ##    o <- sort.int(x, index.return=TRUE, method="quick");
   ##    stopifnot(identical(o, o0));
       sort.int(x, index.return=TRUE, method="quick");
     } # qsort()
 
 

     # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     # Validate arguments
     # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

     readAll <- is.null(indices);
 

     if (.checkArgs) {
       # Argument 'filename':
       if(length(filename) != 1) {

         stop("Argument 'filename' should be a single file: ",

                                               paste(filename, collapse=", "));
       }
       # Expand '~' pathnames to full pathnames.
       filename <- file.path(dirname(filename), basename(filename));
       if (!file.exists(filename)) {
         stop("Cannot read CEL file. File not found: ", filename);
       }

       # Argument 'indices':
       header <- readCelHeader(filename);
       nbrOfCells <- header$total;

       if (readAll) {

         # Read all cells
         indices <- 1:nbrOfCells;
       } else {
         indices <- as.integer(indices);
         if (any(is.na(indices))) {
           stop("Argument 'indices' contains NAs.");
         }
         if (any(indices < 1) || any(indices > nbrOfCells)) {
           stop("Argument 'indices' is out of range [1,", nbrOfCells, "].");
         }
       }

       # Argument 'readMap':
       if (!is.null(readMap)) {

         readMap <- .assertMap(readMap, nbrOfCells);

       }

       # Argument 'verbose':
       if (length(verbose) != 1) {
         stop("Argument 'verbose' must be a single integer.");
       }
       if (!is.finite(as.integer(verbose))) {
         stop("Argument 'verbose' must be an integer: ", verbose);
       }

     } # if (.checkArgs)

     # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     # Remapping cell indices?
     # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

     if (is.null(readMap)) {
       # If not read map and no indices very given, then all cells are read
       # and already in order an no need to sort them.
       # *all cells are read
       reorder <- FALSE;
     } else {

       indices <- readMap[indices];

       reorder <- TRUE;

     }

     # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     # Order cell indices for optimal speed when reading, i.e. minimizing
     # jumping around in the file.
     # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     if (reorder) {

       # qsort() is about 10-15 times faster than using order()!
       # WAS: o <- .Internal(qsort(indices, TRUE));  # From base::sort.int()
       o <- qsort(indices);

       indices <- o$x;

       # WAS: o <- .Internal(qsort(o$ix, TRUE))$ix;  # From base::sort.int()
       o <- qsort(o$ix)$ix;

     }
 

     # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     # Reading CEL file
     # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

     # UNSUPPORTED CASE?
     if (!is.null(indices) && length(indices) == 0L) {
       stop("readCel(..., indices=integer(0)) is not supported.")
     }
 

     cel <- .Call("R_affx_get_cel_file", filename,
                   readHeader,
                   readIntensities, readXY, readXY, readPixels, readStdvs,
                   readOutliers, readMasked,
                   indices,
                   as.integer(verbose), PACKAGE="affxparser");
 

     # Sanity check
     if (is.null(cel)) {
       stop("Failed to read CEL file: ", filename);
     }
 

     # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     # Re-reordering the cell values
     # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     if (reorder) {
       fields <- setdiff(names(cel), c("header", "outliers", "masked"));
       for (name in fields) {
         cel[[name]] <- cel[[name]][o];
       }
     }

     cel;

 } # readCel()
 
 ############################################################################
 # HISTORY:

 # 2012-05-22 [HB]
 # o CRAN POLICY: readCel() and readCelUnits() are no longer calling
 #   .Internal(qsort(...)).

 # 2011-11-18
 # o ROBUSTNESS: Added sanity check that the native code did not return NULL.

 # 2007-12-01
 # o Removed argument 'reorder' from readCel().

 # 2007-01-04

 # o Now 'readMap' is validate using internal .assertMap(), which also

 #   coerces it to an integer vector.
 # o BUG FIX: Using read maps for readCel() would give an error saying
 #   the read map is invalid even when it is not.

 # 2006-04-01
 # o Added argument 'reorder'.

 # 2006-03-29
 # o Added argument '.checkArgs' so that when arguments have already been
 #   checked, for instance by readCelUnits(), we pay less overhead when
 #   calling this function.  file.exists() is a bit slow. /HB
 # 2006-03-28
 # o Unit and cell indices are now one-based. /HB
 ############################################################################