#########################################################################/**
# @RdocFunction compareCdfs
#
# @title "Compares the contents of two CDF files"
#
# @synopsis
#
# \description{
#   @get "title".
# }
#
# \arguments{
#   \item{pathname}{The pathname of the first CDF file.}
#   \item{other}{The pathname of the seconds CDF file.}
#   \item{quick}{If @TRUE, only a subset of the units are compared,
#     otherwise all units are compared.}
#   \item{verbose}{An @integer. The larger the more details are printed.}
#   \item{...}{Not used.}
# }
#
# \value{
#   Returns @TRUE if the two CDF are equal, otherwise @FALSE.  If @FALSE,
#   the attribute \code{reason} contains a string explaining what
#   difference was detected, and the attributes \code{value1} and
#   \code{value2} contain the two objects/values that differs.
# }
#
# \details{
#  The comparison is done with an upper-limit memory usage, regardless of
#  the size of the CDFs.
# }
#
# @author "HB"
#
# \seealso{
#   @see "convertCdf".
# }
#
# @keyword "file"
# @keyword "IO"
#*/#########################################################################
compareCdfs <- function(pathname, other, quick=FALSE, verbose=0, ...) {
  # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  # Local functions
  # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  differentUnit <- function(value1, value2, units) {
    n <- length(units);

    # Done?
    if (n == 0) return(NULL);

    # Cannot narrow down?
    if (length(value1) != n) return(NULL);
    if (length(value2) != n) return(NULL);

    # Compare
    if (n == 1) {
      res <- all.equal(value1, value2);
      # Different?
      if (!identical(res, TRUE)) {
        return(units);
      } else {
        return(NULL);
      }
    }

    half <- floor(n/2);
    head <- 1:half;
    tail <- (half+1):n;

    # Among first half?
    unit <- differentUnit(value1[head], value2[head], units=units[head]);
    if (!is.null(unit)) return(unit);

    # Among second half?
    unit <- differentUnit(value1[tail], value2[tail], units=units[tail]);
    if (!is.null(unit)) return(unit);

    NULL;
  } # differentUnit()

  different <- function(fmtstr, ..., units=NULL, value1=NULL, value2=NULL) {
    res <- FALSE;
    attr(res, "reason") <- sprintf(fmtstr, ...);
    attr(res, "units") <- units;
    attr(res, "value1") <- value1;
    attr(res, "value2") <- value2;
    res;
  } # different()

  # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  # Validate arguments
  # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  # Argument 'pathname':
  # Expand any '~' in the pathname.
  pathname <- file.path(dirname(pathname), basename(pathname));
  if (!file.exists(pathname)) {
    stop("Cannot compare CDFs. File not found: ", pathname);
  }
  # Expand any '~' in the pathname.
  other <- file.path(dirname(other), basename(other));
  if (!file.exists(other)) {
    stop("Cannot compare CDFs. File not found: ", other);
  }

  # Argument 'verbose':
  verbose <- as.integer(verbose);


  if (verbose >= 1) {
    cat("Comparing CDFs...\n");
    cat("  CDF 1: ", pathname, "\n", sep="");
    cat("  CDF 2: ", other, "\n", sep="");
  }

  # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  # Compare headers
  # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  if (verbose >= 1)
    cat("  Comparing CDF headers...\n");
  h1 <- readCdfHeader(pathname);
  h2 <- readCdfHeader(other);
  for (ff in c("nrows", "ncols", "nunits", "nqcunits", "refseq")) {
    if (!identical(h1[[ff]], h2[[ff]]))
      return(different("%s: %s != %s", ff, h1[[ff]], h2[[ff]]));
  }
  if (verbose >= 1)
    cat("  Comparing CDF headers...done\n");

  # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  # Compare QC units
  # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  if (verbose >= 1)
    cat("  Comparing QC units...\n");
  units <- seq_len(h1$nqcunits);
  while (length(units) > 0) {
    head <- 1:min(length(units),10);
    uu <- units[head];
    units <- units[-head];
    v1 <- readCdfQc(pathname, units=uu);
    v2 <- readCdfQc(other, units=uu);
    res <- all.equal(v1, v2);
    if (!identical(res, TRUE)) {
      badUnit <- differentUnit(value1=v1, value2=v2, units=uu);
      if (!is.null(badUnit)) {
        msg <- sprintf("Detected (at least one) QC unit that differ: %d", badUnit);
        units <- badUnit;
        idx <- match(badUnit, uu);
        v1 <- v1[idx];
        v2 <- v2[idx];
      } else {
        msg <- sprintf("Detected (at least one) QC unit that differ amount units %d to %d", min(uu), max(uu));
      }
      return(different(msg, units=units, value1=v1, value2=v2));
    }
    v1 <- v2 <- uu <- head <- NULL; # Not needed anymore
  }
  if (verbose >= 1)
    cat("  Comparing QC units...done\n");


  # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  # Compare units
  # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  if (verbose >= 1) {
    cat("  Comparing units...\n");
    if (quick)
      cat("    Quick mode. Will only check a subset of the units...done\n");
  }
  if (verbose >= 2)
    cat("    Progress: ");
  units <- seq_len(h1$nunits);
  count <- 0;
  while (length(units) > 0) {
    head <- 1:min(length(units),500);
    if (verbose >= 2)
      cat(sprintf("%d%%, ", as.integer(100*count/h1$nunits)));
    uu <- units[head];
    units <- units[-head];
    v1 <- readCdf(pathname, units=uu);
    v2 <- readCdf(other, units=uu);
    res <- all.equal(v1, v2);
    if (!identical(res, TRUE)) {
      badUnit <- differentUnit(value1=v1, value2=v2, units=uu);
      if (!is.null(badUnit)) {
        msg <- sprintf("Detected (at least one) unit that differ: %d", badUnit);
        units <- badUnit;
        idx <- match(badUnit, uu);
        v1 <- v1[idx];
        v2 <- v2[idx];
      } else {
        msg <- sprintf("Detected (at least one) unit that differ amount units %d to %d", min(uu), max(uu));
      }
      return(different(msg, units=units, value1=v1, value2=v2));
    }
    count <- count + length(uu);
    if (quick)
      break;
    v1 <- v2 <- uu <- head <- NULL; # Not needed anymore
  }
  if (verbose >= 2)
    cat("100%.\n");
  if (verbose >= 1)
    cat("  Comparing units...done\n");

  if (verbose >= 1)
    cat("Comparing CDFs...done\n");

  TRUE;
} # compareCdfs()


############################################################################
# HISTORY:
# 2012-10-18
# o Now compareCdfs() gives a more precise 'reason' attribute when there
#   is a difference in (regular or QC) units.  It narrows down the first
#   unit that differs and reports it unit number.
# 2006-09-10
# o Added argument 'quick' to check only a subset of the units.
# 2006-09-09
# o Created.
############################################################################