H5P.R

####################################################
## General Property List Operations
####################################################

#' Create a new HDF5 property list
#'
#' @param type A character name of a property list type. See `h5const("H5P")`
#' for possible property list types.
#' @param native Defunct! Doesn't achieve anything for property lists.
#'
#' @export
H5Pcreate <- function(type = h5default("H5P"), native = FALSE) {
  type <- h5checkConstants("H5P", type)
  pid <- .Call("_H5Pcreate", type, PACKAGE = "rhdf5")
  if (pid > 0) {
    h5plist <- new("H5IdComponent", ID = pid, native = native)
  } else {
    message("HDF5: unable to create property list")
    h5plist <- FALSE
  }
  invisible(h5plist)
}

#' Return the property list class identifier for a property list
#'
#' @param h5plist [H5IdComponent-class] object representing any type of HDF5
#' property list.
#'
#' @export
H5Pget_class <- function(h5plist) {
  h5checktype(h5plist, "plist")
  pclid <- .Call("_H5Pget_class", h5plist@ID, PACKAGE = "rhdf5")
  if (pclid > 0) {
    h5plistclass <- new("H5IdComponent", ID = pclid, native = h5plist@native)
  } else {
    message("HDF5: unable to get property list class")
    h5plistclass <- FALSE
  }
  invisible(h5plistclass)
}

#' Copy an existing property list to create a new property list
#'
#' @param h5plist [H5IdComponent-class] object representing the property list
#' to be copied.
#'
#' @export
H5Pcopy <- function(h5plist) {
  h5checktype(h5plist, "plist")
  pid <- .Call("_H5Pcopy", h5plist@ID, PACKAGE = "rhdf5")
  if (pid > 0) {
    h5plistnew <- new("H5IdComponent", ID = pid, native = h5plist@native)
  } else {
    message("HDF5: unable to copy property list")
    h5plistnew <- FALSE
  }
  invisible(h5plistnew)
}

#' Close and release a property list
#'
#' `H5Pclose()` terminates access to a property list. All property lists
#' should be closed when they no longer need to be accessed. This
#' frees resources used by the property list.  Failing to call `H5Pclose()`
#' can lead to memory leakage over time.
#'
#' @param h5plist [H5IdComponent-class] object representing the property list
#' to close.
#'
#' @export
H5Pclose <- function(h5plist) {
  h5checktype(h5plist, "plist")
  invisible(.Call("_H5Pclose", h5plist@ID, PACKAGE = "rhdf5"))
}

####################################################
## File Creation Properties
####################################################

#' Get version information for objects in a file creation property list
#'
#' @param h5plist [H5IdComponent-class] object representing the file creation property list
#' @returns Named integer vector
#' @export
H5Pget_version <- function(h5plist) {
  h5checktype(h5plist, "plist")
  .Call("_H5Pget_version", h5plist@ID, PACKAGE = "rhdf5")
}

#' Get and set the user block size
#' @param h5plist [H5IdComponent-class] object representing the file creation property list
#' @param size of the user block in bytes
#' @rdname H5P_userblock
#' @export
H5Pset_userblock <- function(h5plist, size) {
  h5checktype(h5plist, "plist")
  invisible(.Call("_H5Pset_userblock", h5plist@ID, size, PACKAGE = "rhdf5"))
}

#' @rdname H5P_userblock
#' @export
H5Pget_userblock <- function(h5plist) {
  h5checktype(h5plist, "plist")
  .Call("_H5Pget_userblock", h5plist@ID, PACKAGE = "rhdf5")
}

#' Get and set the sizes of offsets and lengths used in an HDF5 file
#'
#' @param h5plist [H5IdComponent-class] object representing the file creation property list
#' @param sizeof_addr Offset size in bytes
#' @param sizeof_size Length size in bytes
#' @rdname H5P_sizes
#' @export
H5Pset_sizes <- function(h5plist, sizeof_addr, sizeof_size) {
  h5checktype(h5plist, "plist")
  invisible(.Call(
    "_H5Pset_sizes",
    h5plist@ID,
    sizeof_addr,
    sizeof_size,
    PACKAGE = "rhdf5"
  ))
}

#' @rdname H5P_sizes
#' @export
H5Pget_sizes <- function(h5plist) {
  h5checktype(h5plist, "plist")
  .Call("_H5Pget_sizes", h5plist@ID, PACKAGE = "rhdf5")
}

#' Get and set the size of the symbol table B-tree 1/2 rank and the leaf node 1/2 size
#'
#' @param h5plist [H5IdComponent-class] object representing the file creation property list
#' @param ik Symbol table B-tree 1/2 rank
#' @param lk Symbol table leaf node 1/2 size
#' @rdname H5P_sym_k
#' @export
H5Pset_sym_k <- function(h5plist, ik, lk) {
  h5checktype(h5plist, "plist")
  invisible(.Call("_H5Pset_sym_k", h5plist@ID, ik, lk, PACKAGE = "rhdf5"))
}

#' @rdname H5P_sym_k
#' @export
H5Pget_sym_k <- function(h5plist) {
  h5checktype(h5plist, "plist")
  .Call("_H5Pget_sym_k", h5plist@ID, PACKAGE = "rhdf5")
}

#' Get and set the 1/2 rank of an indexed storage B-tree
#'
#' @param h5plist [H5IdComponent-class] object representing the file creation property list
#' @param ik chunked Storage B-tree 1/2 rank
#' @rdname H5P_istore_k
#' @export
H5Pset_istore_k <- function(h5plist, ik) {
  h5checktype(h5plist, "plist")
  invisible(.Call("_H5Pset_istore_k", h5plist@ID, ik, PACKAGE = "rhdf5"))
}

#' @rdname H5P_istore_k
#' @export
H5Pget_istore_k <- function(h5plist) {
  h5checktype(h5plist, "plist")
  .Call("_H5Pget_istore_k", h5plist@ID, PACKAGE = "rhdf5")
}

#' Get and set the number of object header message indexes
#'
#' @param h5plist [H5IdComponent-class] object representing the file creation property list
#' @param nindexes Number of shared object header message indexes to be available in files
#' @rdname H5P_shared_mesg_nindexes
#' @export
H5Pset_shared_mesg_nindexes <- function(h5plist, nindexes) {
  h5checktype(h5plist, "plist")
  invisible(.Call(
    "_H5Pset_shared_mesg_nindexes",
    h5plist@ID,
    nindexes,
    PACKAGE = "rhdf5"
  ))
}

#' @rdname H5P_shared_mesg_nindexes
#' @export
H5Pget_shared_mesg_nindexes <- function(h5plist) {
  h5checktype(h5plist, "plist")
  .Call("_H5Pget_shared_mesg_nindexes", h5plist@ID, PACKAGE = "rhdf5")
}

#' Get and set shared object header message index properties
#'
#' @param h5plist [H5IdComponent-class] object representing the file creation
#'   property list
#' @param index_num Index being configured.  Indices use C-style 0-based counting,
#'   so the first index will be numbered 0.
#' @param mesg_type_flags Character specifying the types of messages that may be stored in this index.
#'   Valid values can be found with `h5const(type = "H5O_SHMESG_FLAG")`
#' @param min_mesg_size Minimum message size
#'
#' @returns `H5Pget_shared_mesg_index()` returns a list of length 2. The first element is the types of messages
#' that may be stored in the index, the second element is the minimum message size.
#'
#' @rdname H5Pshared_mesg_index
#' @export
H5Pset_shared_mesg_index <- function(
  h5plist,
  index_num,
  mesg_type_flags = h5default(type = "H5O_SHMESG_FLAG"),
  min_mesg_size
) {
  h5checktype(h5plist, "plist")
  mesg_type_flags <- h5checkConstants("H5O_SHMESG_FLAG", mesg_type_flags)
  invisible(.Call(
    "_H5Pset_shared_mesg_index",
    h5plist@ID,
    index_num,
    mesg_type_flags,
    min_mesg_size,
    PACKAGE = "rhdf5"
  ))
}

#' @rdname H5Pshared_mesg_index
#' @export
H5Pget_shared_mesg_index <- function(h5plist, index_num) {
  h5checktype(h5plist, "plist")
  res <- .Call(
    "_H5Pget_shared_mesg_index",
    h5plist@ID,
    index_num,
    PACKAGE = "rhdf5"
  )
  return(list(
    type_flags = h5const2String("H5O_SHMESG_FLAG", res[1]),
    size = res[2]
  ))
}

#' Get and set threshold values for storage of shared object header message indexes
#'
#' @param h5plist [H5IdComponent-class] object representing the file creation property list
#' @param max_list Threshold above which storage shifts from list to B-tree
#' @param min_btree Threshold below which storage reverts to list format
#' @rdname H5P_shared_mesg_phase_change
#' @export
H5Pset_shared_mesg_phase_change <- function(h5plist, max_list, min_btree) {
  h5checktype(h5plist, "plist")
  invisible(.Call(
    "_H5Pset_shared_mesg_phase_change",
    h5plist@ID,
    max_list,
    min_btree,
    PACKAGE = "rhdf5"
  ))
}

#' @rdname H5P_shared_mesg_phase_change
#' @export
H5Pget_shared_mesg_phase_change <- function(h5plist) {
  h5checktype(h5plist, "plist")
  .Call("_H5Pget_shared_mesg_phase_change", h5plist@ID, PACKAGE = "rhdf5")
}

####################################################
## File Access Properties
####################################################

#' Set the read-only S3 virtual file driver
#'
#' The read-only S3 virtual file driver can be used to read files hosted
#' remotely on Amazon's S3 storage.
#'
#' @details To access files in a private Amazon S3 bucket you will need to
#'   provide three additional details: The AWS region where the files are
#'   hosted, your AWS access key ID, and your AWS secret access key.  More
#'   information on how to obtain AWS access keys can be found at
#'   <https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys>.
#'   These are provided as a list to the `s3credentials` argument.  If you
#'   are accessing public data this argument should be `NULL`.
#'
#' @param h5plist [H5IdComponent-class] object representing a file access
#' property list.
#' @param s3credentials Either `NULL` or a list of length 3 specifying the AWS access credentials (see details).
#'
#' @examples
#'
#' ## this doesn't work on the Bioconductor Mac build machine
#' \dontrun{
#' pid <- H5Pcreate("H5P_FILE_ACCESS")
#' H5Pset_fapl_ros3(pid)
#' H5Pclose(pid)
#' }
#'
#' @export
H5Pset_fapl_ros3 <- function(h5plist, s3credentials = NULL) {
  ## this should really check it's a fapl, not just a plist.
  h5checktype(h5plist, "plist")

  ## only do authentication if s3credentials are provided
  if (!is.null(s3credentials)) {
    auth <- TRUE
    aws_region <- s3credentials[[1]]
    access_key_id <- s3credentials[[2]]
    secret_access_key <- s3credentials[[3]]
  } else {
    auth <- FALSE
    aws_region <- access_key_id <- secret_access_key <- ""
  }

  res <- .Call(
    "_H5Pset_fapl_ros3",
    h5plist@ID,
    auth,
    aws_region,
    access_key_id,
    secret_access_key,
    PACKAGE = "rhdf5"
  )
  invisible(res)
}

#' Control the range of HDF5 library versions that will be compatible with
#' a file.
#'
#'
#' @param h5plist [H5IdComponent-class] object representing a file access
#' property list.
#' @param libver_low,libver_high Define the earliest and latest versions of
#' the HDF5 library that will be used when writing object in the file.
#'
#' @name H5P_libver_bounds
NULL

#' @rdname H5P_libver_bounds
#' @export
H5Pset_libver_bounds <- function(
  h5plist,
  libver_low = "H5F_LIBVER_EARLIEST",
  libver_high = "H5F_LIBVER_LATEST"
) {
  h5checktype(h5plist, "plist")
  libver_low <- h5checkConstants("H5F_LIBVER", libver_low)
  libver_high <- h5checkConstants("H5F_LIBVER", libver_high)
  res <- .Call(
    "_H5Pset_libver_bounds",
    h5plist@ID,
    libver_low,
    libver_high,
    PACKAGE = "rhdf5"
  )
  invisible(res)
}

#' @rdname H5P_libver_bounds
#' @export
H5Pget_libver_bounds <- function(h5plist) {
  h5checktype(h5plist, "plist")
  res <- .Call("_H5Pget_libver_bounds", h5plist@ID, PACKAGE = "rhdf5")
  res <- h5const2String("H5F_LIBVER", res)
  names(res) <- c("libver_low", "libver_high")
  res
}

####################################################
## Link Creation Properties
####################################################

H5Pset_char_encoding <- function(h5plist, encoding = h5default("H5T_CSET")) {
  h5checktypeAndPLC(h5plist, "H5P_LINK_CREATE")
  encoding <- h5checkConstants("H5T_CSET", encoding)
  res <- .Call("_H5Pset_char_encoding", h5plist@ID, encoding, PACKAGE = "rhdf5")
  invisible(res)
}

H5Pget_char_encoding <- function(h5plist) {
  h5checktypeAndPLC(h5plist, "H5P_LINK_CREATE")
  res <- .Call("_H5Pget_char_encoding", h5plist@ID, PACKAGE = "rhdf5")
  res <- h5const2String("H5T_CSET", res)
  res
}

#' Get and set whether to create missing intermediate groups
#'
#' @param h5plist An object of class [H5IdComponent-class] representing a link
#'   creation property list.
#' @param create_groups A logical of length 1 specifying whether missing
#'   groups should be created when a new object is created.  Default is `TRUE`.
#'
#' @examples
#' pid <- H5Pcreate("H5P_LINK_CREATE")
#'
#' ## by default intermediate groups are not created
#' H5Pget_create_intermediate_group(pid)
#'
#' ## Change the setting so groups will be created
#'
#' H5Pget_create_intermediate_group(pid)
#'
#' ## tidy up
#' H5Pclose(pid)
#'
#' @name H5P_create_intermediate_group
NULL

#' @rdname H5P_create_intermediate_group
#' @export
H5Pset_create_intermediate_group <- function(h5plist, create_groups = TRUE) {
  h5checktypeAndPLC(h5plist, "H5P_LINK_CREATE")
  if (!is.logical(create_groups)) {
    stop("The 'create_groups' argument should be either TRUE or FALSE")
  }

  crt_intermed_group <- as.integer(create_groups)
  res <- .Call(
    "_H5Pset_create_intermediate_group",
    h5plist@ID,
    crt_intermed_group,
    PACKAGE = "rhdf5"
  )
  invisible(res)
}

#' @rdname H5P_create_intermediate_group
#' @export
H5Pget_create_intermediate_group <- function(h5plist) {
  h5checktypeAndPLC(h5plist, "H5P_LINK_CREATE")
  res <- .Call(
    "_H5Pget_create_intermediate_group",
    h5plist@ID,
    PACKAGE = "rhdf5"
  )
  res
}

####################################################
## Dataset Creation Properties
####################################################

#' Get and set the type of storage used to store the raw data for a dataset
#'
#' Possible options for the `layout` argument are:
#' * `H5D_COMPACT`
#' * `H5D_CONTIGUOUS`
#' * `H5D_CHUNKED`
#' * `H5D_VIRTUAL`
#'
#' The names of the layout types can also be obtained via `h5const("H5D")`.
#'
#' @param h5plist An object of class [H5IdComponent-class] representing a dataset creation property list.
#' @param layout A character giving the name of a dataset layout type.
#'
#' @name H5P_layout
NULL

#' @rdname H5P_layout
#' @export
H5Pset_layout <- function(h5plist, layout = h5default("H5D")) {
  h5checktypeAndPLC(h5plist, "H5P_DATASET_CREATE")
  layout <- h5checkConstants("H5D", layout)
  res <- .Call("_H5Pset_layout", h5plist@ID, layout, PACKAGE = "rhdf5")
  invisible(res)
}

#' @rdname H5P_layout
#' @export
H5Pget_layout <- function(h5plist) {
  h5checktypeAndPLC(h5plist, "H5P_DATASET_CREATE")
  res <- .Call("_H5Pget_layout", h5plist@ID, PACKAGE = "rhdf5")
  res <- h5const2String("H5D", res)
  res
}

#' Get and set the size of the chunks used to store a chunked layout dataset
#'
#' @details Note that a necessary side effect of running this function is that the
#' layout of the dataset will be changes to `H5D_CHUNKED` if it is not already set to this.
#'
#' @param h5plist An object of class [H5IdComponent-class] representing a dataset creation property list.
#' @param dim The chunk size used to store the dataset. This argument should be an integer vector of the same length as
#' the number of dimensions of the dataset the dataset creation property list will be applied to.
#'
#' @seealso [H5Pset_layout()]
#'
#' @name H5P_chunk
NULL

#' @rdname H5P_chunk
#' @export
H5Pset_chunk <- function(h5plist, dim) {
  h5checktypeAndPLC(h5plist, "H5P_DATASET_CREATE")
  if (!is.null(dim) && !h5plist@native) {
    dim <- rev(as.integer(dim))
  }
  res <- .Call("_H5Pset_chunk", h5plist@ID, dim, PACKAGE = "rhdf5")
  invisible(res)
}

#' @rdname H5P_chunk
#' @export
H5Pget_chunk <- function(h5plist) {
  h5checktypeAndPLC(h5plist, "H5P_DATASET_CREATE")
  res <- .Call("_H5Pget_chunk", h5plist@ID, PACKAGE = "rhdf5")
  res
}

#' Add the deflate compression filter to the chunk processing pipeline.
#'
#' Valid values for the compression level range from 0 (no compression) to 9
#' (best compression, slowest speed). Note that applying this function with
#' `level = 0` does not mean the filter is removed.  It is still part of the
#' filter pipeline, but no compression is performed.  The filter will still need
#' to be available on any system that reads a file created with this setting
#'
#' @param h5plist Object of class [H5IdComponent-class] representing a dataset
#'   creation property list.
#' @param level Integer giving the compression level to use.  Valid values are
#'   from 0 to 9.
#'
#' @export
H5Pset_deflate <- function(h5plist, level) {
  h5checktypeAndPLC(h5plist, "H5P_DATASET_CREATE")
  level <- as.integer(level)
  res <- .Call("_H5Pset_deflate", h5plist@ID, level, PACKAGE = "rhdf5")
  invisible(res)
}

#' Set the fill value for an HDF5 dataset
#'
#' `H5Pset_fill_value` sets the fill value for a dataset in the dataset creation property list.
#'
#' @param h5plist An object of class [H5IdComponent-class] representing a
#'   dataset creation property list.
#' @param value The default fill value of the dataset. A vector of length 1.
#'
#' @seealso [H5P_fill_time],[H5Pfill_value_defined]
#'
#' @name H5P_fill_value
NULL

#' @rdname H5P_fill_value
#' @export
H5Pset_fill_value <- function(h5plist, value) {
  if (length(value) > 1L) {
    stop("'value' must be a vector of length 1.")
  }

  h5checktypeAndPLC(h5plist, "H5P_DATASET_CREATE")
  storage.mode <- storage.mode(value)
  tid <- switch(
    storage.mode,
    double = h5constants$H5T["H5T_IEEE_F64LE"],
    integer = h5constants$H5T["H5T_STD_I32LE"],
    logical = h5constants$H5T["H5T_STD_I8LE"],
    character = {
      tid <- H5Tcopy("H5T_C_S1")
      on.exit(H5Tclose(tid))
      size <- nchar(value, type = "bytes")
      H5Tset_size(tid, size)
      H5Tset_strpad(tid, strpad = "NULLPAD")
      if (Encoding(value) == "UTF-8") {
        cset <- "UTF-8"
      } else {
        cset <- "ASCII"
      }
      H5Tset_cset(tid, cset = cset)
      tid
    },
    {
      stop(
        "datatype ",
        storage.mode,
        " not supported. Try 'double', 'integer', or 'character'."
      )
    }
  )
  res <- .Call("_H5Pset_fill_value", h5plist@ID, tid, value, PACKAGE = "rhdf5")

  invisible(res)
}

#' Determine whether a property list has a fill value defined
#'
#' @param h5plist Object of class [H5IdComponent-class] representing a dataset
#'   creation property list.
#'
#' @returns `TRUE` if the fill value is defined, `FALSE` if not.  Will return
#'   `NULL` if there is a problem determining the status of the fill value.
#'
#' @details  Note that the return value for this function is slightly different
#'   from the C version.  The C API provides three return types and can, in the
#'   case that a fill value is defined, differentiate whether the value is the
#'   HDF5 library default or has been set by the application.
#'
#' @export
H5Pfill_value_defined <- function(h5plist) {
  h5checktypeAndPLC(h5plist, "H5P_DATASET_CREATE")
  res <- .Call("_H5Pfill_value_defined", h5plist@ID, PACKAGE = "rhdf5")
  res
}

#' Set the time when fill values are written to a dataset
#'
#' @param h5plist An object of class [H5IdComponent-class] representing a
#'   dataset creation property list.
#' @param fill_time When the fill values should be written.  Possible options
#' can be listed with `h5const("H5D_FILL_TIME")`.
#'
#' @name H5P_fill_time
NULL

#' @rdname H5P_fill_time
#' @export
H5Pset_fill_time <- function(h5plist, fill_time = h5default("H5D_FILL_TIME")) {
  h5checktypeAndPLC(h5plist, "H5P_DATASET_CREATE")
  fill_time <- h5checkConstants("H5D_FILL_TIME", fill_time)
  res <- .Call("_H5Pset_fill_time", h5plist@ID, fill_time, PACKAGE = "rhdf5")
  invisible(res)
}

#' @rdname H5P_fill_time
#' @export
H5Pget_fill_time <- function(h5plist) {
  h5checktypeAndPLC(h5plist, "H5P_DATASET_CREATE")
  res <- .Call("_H5Pget_fill_time", h5plist@ID, PACKAGE = "rhdf5")
  res <- h5const2String("H5D_FILL_TIME", res)
  res
}

H5Pset_alloc_time <- function(
  h5plist,
  alloc_time = h5default("H5D_ALLOC_TIME")
) {
  h5checktypeAndPLC(h5plist, "H5P_DATASET_CREATE")
  alloc_time <- h5checkConstants("H5D_ALLOC_TIME", alloc_time)
  res <- .Call("_H5Pset_alloc_time", h5plist@ID, alloc_time, PACKAGE = "rhdf5")
  invisible(res)
}

H5Pget_alloc_time <- function(h5plist) {
  h5checktypeAndPLC(h5plist, "H5P_DATASET_CREATE")
  res <- .Call("_H5Pget_alloc_time", h5plist@ID, PACKAGE = "rhdf5")
  res <- h5const2String("H5D_ALLOC_TIME", res)
  res
}

#' Query dataset filter properties.
#'
#' Return information about the filter pipeline applied to a dataset creation
#' property list.
#'
#' * `H5Pall_filters_avail()` checks whether all filters required to process a
#' dataset are available to **rhdf5**.  This can be required if reading files
#' created with other HDF5 software.
#' * `H5Pget_nfilters()` returns the number of
#' filters in the dataset chunk processing pipeline.
#' * `H5Pget_filter()`
#' provides details of a specific filter in the pipeline. This includes the
#' filter name and the parameters provided to it e.g. compression level.
#'
#' @param h5plist Object of class [H5IdComponent-class] representing a dataset
#'   creation property list.
#' @param idx Integer of length 1.  This argument selects which filter to return
#'   information about.  Indexing is R-style 1-based.

#' @rdname H5P_filters
#' @export
H5Pall_filters_avail <- function(h5plist) {
  h5checktypeAndPLC(h5plist, "H5P_DATASET_CREATE")
  res <- .Call("_H5Pall_filters_avail", h5plist@ID, PACKAGE = "rhdf5")
  return(res)
}

#' @rdname H5P_filters
#' @export
H5Pget_nfilters <- function(h5plist) {
  h5checktypeAndPLC(h5plist, "H5P_DATASET_CREATE")
  res <- .Call("_H5Pget_nfilters", h5plist@ID, PACKAGE = "rhdf5")
  res
}

#' @rdname H5P_filters
#' @export
H5Pget_filter <- function(h5plist, idx) {
  h5checktypeAndPLC(h5plist, "H5P_DATASET_CREATE")
  idx <- as.integer(idx)

  if (idx < 1 || idx > H5Pget_nfilters(h5plist)) {
    stop(
      "'idx' argument is outside the range of filters set on this property list.",
      call. = FALSE
    )
  }

  res <- .Call("_H5Pget_filter", h5plist@ID, idx - 1L, PACKAGE = "rhdf5")
  return(res)
}

#' Add a filter to the dataset filter pipeline.
#'
#' @param h5plist Object of class [H5IdComponent-class] representing a dataset
#'   creation property list.
#' @param filter_id Integer of length 1, giving the ID of the filter to be used.
#' @param is_mandatory Logical of length 1.  Filters can be either optional or
#'   mandatory.  If this argument is set to `FALSE` the filter won't be applied
#'   to a chunk in the case of failure, but the data will still be written.
#'   Setting to `TRUE` will result in a failure when writing the dataset if the
#'   filter fails for some reason.
#' @param cd_values Integer vector giving parameters to be supplied to the
#'   filter. No guidance is given for the number of values supplied here, it is
#'   specific to each filter and the user is expected to know appropriate
#'   options for the requested filter.
#' @export
H5Pset_filter <- function(h5plist, filter_id, is_mandatory = FALSE, cd_values) {
  h5checktypeAndPLC(h5plist, "H5P_DATASET_CREATE")
  filter_id <- as.integer(filter_id)
  is_mandatory <- as.logical(is_mandatory)
  cd_values <- as.integer(cd_values)

  res <- .Call(
    "_H5Pset_filter",
    h5plist@ID,
    filter_id,
    is_mandatory,
    cd_values,
    PACKAGE = "rhdf5"
  )
  return(res)
}

#' Add the shuffle filter to the chunk processing pipeline.
#'
#' @param h5plist Object of class [H5IdComponent-class] representing a dataset
#' creation property list.
#'
#' @returns Returns (invisibly) an integer vector of length 1.  The only
#'   element of this vector will be non-negative if the filter was set
#'   successfully and negative otherwise.
#'
#' @export
H5Pset_shuffle <- function(h5plist) {
  h5checktypeAndPLC(h5plist, "H5P_DATASET_CREATE")
  res <- .Call("_H5Pset_shuffle", h5plist@ID, PACKAGE = "rhdf5")
  invisible(res)
}

#' Add the N-Bit filter to the chunk processing pipeline.
#'
#' @param h5plist Object of class [H5IdComponent-class] representing a dataset
#'   creation property list.
#'
#' @returns Returns (invisibly) an integer vector of length 1.  The only
#'   element of this vector will be non-negative if the filter was set
#'   successfully and negative otherwise.
#'
#' @export
H5Pset_nbit <- function(h5plist) {
  h5checktypeAndPLC(h5plist, "H5P_DATASET_CREATE")
  res <- .Call("_H5Pset_nbit", h5plist@ID, PACKAGE = "rhdf5")
  invisible(res)
}

#' Add the SZIP compression filter to the chunk processing pipeline.
#'
#' @param h5plist Object of class [H5IdComponent-class] representing a dataset
#' creation property list.
#' @param options_mask,pixels_per_block Integer vectors of length 1, setting parameters
#' of the SZIP algorithm. See <https://portal.hdfgroup.org/display/HDF5/H5P_SET_SZIP> for more details.
#'
#' @references <https://portal.hdfgroup.org/display/HDF5/Szip+Compression+in+HDF+Products>
#'
#' @export
H5Pset_szip <- function(h5plist, options_mask, pixels_per_block) {
  h5checktypeAndPLC(h5plist, "H5P_DATASET_CREATE")
  options_mask <- as.integer(options_mask)
  pixels_per_block <- as.integer(pixels_per_block)
  res <- .Call(
    "_H5Pset_szip",
    h5plist@ID,
    options_mask,
    pixels_per_block,
    PACKAGE = "rhdf5"
  )
  invisible(res)
}


####################################################
## Dataset Access Properties
####################################################

#' Set parameters for the raw data chunk cache
#'
#' @param h5plist Object of class [H5IdComponent-class] representing a dataset
#'   access property list.
#' @param rdcc_nslots Integer defining the number of chunk slots in the raw data
#'   chunk cache for this dataset.
#' @param rdcc_nbytes Integer setting the total size of the raw data chunk cache
#'   for this dataset in bytes. In most cases increasing this number will
#'   improve performance, as long as you have enough free memory. The default
#'   size is 1 MB
#' @param rdcc_w0 Numeric value defining the chunk preemption policy.  Must be between
#'   `0` and `1` inclusive.
#'
#' @name H5P_chunk_cache
NULL

#' @rdname H5P_chunk_cache
#' @export
H5Pset_chunk_cache <- function(h5plist, rdcc_nslots, rdcc_nbytes, rdcc_w0) {
  h5checktypeAndPLC(h5plist, "H5P_DATASET_ACCESS")
  rdcc_nslots <- as.integer(rdcc_nslots)
  rdcc_nbytes <- as.integer(rdcc_nbytes)
  rdcc_w0 <- as.double(rdcc_w0)
  res <- .Call(
    "_H5Pset_chunk_cache",
    h5plist@ID,
    rdcc_nslots,
    rdcc_nbytes,
    rdcc_w0,
    PACKAGE = "rhdf5"
  )
  invisible(res)
}


####################################################
## Object Creation Properties
####################################################

#' Set whether to record timestamps for operations performed on an HDF5 object.
#'
#' @details Objects created using high-level **rhdf5** functions like
#'   [h5createDataset()] will have this setting turned off. This was done to
#'   ensure otherwise identical files returned the same md5 hash. This differs
#'   from the default setting in HDF5, which is for objects to record the times
#'   operations were performed on them.
#'
#' @param h5plist An [H5IdComponent-class] object representing an object
#'   creation property list.
#' @param track_times `logical` specifying whether times associated with an
#'   object should recorded.
#'
#' @name H5Pobject_track_times
NULL

#' @rdname H5Pobject_track_times
#' @export
H5Pset_obj_track_times <- function(h5plist, track_times = TRUE) {
  if (!is.logical(track_times) || is.na(track_times)) {
    stop("Argument 'track_times' must be either TRUE or FALSE")
  }

  res <- .Call(
    "_H5Pset_obj_track_times",
    h5plist@ID,
    as.integer(track_times),
    PACKAGE = "rhdf5"
  )
  invisible(res)
}

#' @rdname H5Pobject_track_times
#' @export
H5Pget_obj_track_times <- function(h5plist) {
  res <- .Call("_H5Pget_obj_track_times", h5plist@ID, PACKAGE = "rhdf5")
  return(res)
}

####################################################
## Generic Property Operations (Advanced)
####################################################

H5Pequal <- function(h5plistclass1, h5plistclass2) {
  h5checktype(h5plistclass1, "plistclass")
  h5checktype(h5plistclass2, "plistclass")
  res <- .Call(
    "_H5Pequal",
    h5plistclass1@ID,
    h5plistclass2@ID,
    PACKAGE = "rhdf5"
  )
  as.logical(res)
}

H5Pclose_class <- function(h5plistclass) {
  h5checktype(h5plistclass, "plistclass")
  invisible(.Call("_H5Pclose_class", h5plistclass@ID, PACKAGE = "rhdf5"))
}