mtblr: Tools to work with 'mtbl' files

# This file was generated by Rcpp::compileAttributes
# Generator token: 10BE3573-1514-4C36-9D1C-5A225CD40393

#' Open an mtbl file
#'
#' @param path full path to mtbl file
#' @export
#' @examples
#' mtbl <- read_mtbl(system.file("extdata/sample.mtbl", package="mtblr"))
read_mtbl <- function(path) {
    .Call('mtblr_read_mtbl', PACKAGE = 'mtblr', path)
}

#' Retrieve the number of records in an open mtbl file
#'
#' @param x mtbl file opened with \code{read_mtbl()}
#' @export
#' @examples
#' mtbl <- read_mtbl(system.file("extdata/sample.mtbl", package="mtblr"))
#' mtbl_length(mtbl)
mtbl_length <- function(x) {
    .Call('mtblr_mtbl_length', PACKAGE = 'mtblr', x)
}

#' Start an iterator over an mtbl file
#'
#' TODO add a parameter to pass in an R function to evaluate
#' just like in a real iterator
#'
#' @param x mtbl file opened with \code{read_mtbl()}
#' @export
#' @examples
#' mtbl <- read_mtbl(system.file("extdata/sample.mtbl", package="mtblr"))
#' mp <- mtbl_map(mtbl)
#' mtbl_iter_close(mp)
mtbl_map <- function(x) {
    .Call('mtblr_mtbl_map', PACKAGE = 'mtblr', x)
}

#' Iterate over mtbl file entries
#'
#' Works with \code{mtbl_map()} and \code{mtbl_get()}
#'
#' If the number of available entries is less than \code{n}, a \code{list}
#' of the actual number of remaining entries is returned. Otherwise a \code{list}
#' of \code{n} entries is returned.
#'
#' @param x an iterator started with \code{mtbl_map()} or \code{mtbl_get()}
#' @param n number of records to return for this iteration. It's inefficient to
#'        sequentially iterate over large mtbl file but large values of \code{n}
#'        are also inefficent. \code{100} has been an optimal value in mtbl
#'        files used in Project Sonar. YMMV.
#' @export
#' @examples
#' mtbl <- read_mtbl(system.file("extdata/sample.mtbl", package="mtblr"))
#' mp <- mtbl_map(mtbl)
#' (mtbl_next(mp))
#' mtbl_iter_close(mp)
mtbl_next <- function(x, n = 100L) {
    .Call('mtblr_mtbl_next', PACKAGE = 'mtblr', x, n)
}

#' Return all the keys of an mtbl
#'
#' Remember that mtbl files are (in general) HUGE. This could take
#' a while and have a very large result.
#'
#' @param x an mtbl file opened with \code{read_mtbl()}
#' @export
#' @examples
#' mtbl <- read_mtbl(system.file("extdata/sample.mtbl", package="mtblr"))
#' head(mtbl_keys(mtbl))
mtbl_keys <- function(x) {
    .Call('mtblr_mtbl_keys', PACKAGE = 'mtblr', x)
}

#' Return all the values of an mtbl
#'
#' Remember that mtbl files are (in general) HUGE. This could take
#' a while and have a very large result.
#'
#' @param x an mtbl file opened with \code{read_mtbl()}
#' @export
#' @examples
#' mtbl <- read_mtbl(system.file("extdata/sample.mtbl", package="mtblr"))
#' head(mtbl_values(mtbl))
#' @export
mtbl_values <- function(x) {
    .Call('mtblr_mtbl_values', PACKAGE = 'mtblr', x)
}

#' Export mtbl \emph{values} to a file
#'
#' Given an \code{mtbl} file opened with \code{read_mtbl()}, this function
#' will export each value from the mtbl key/value pair to \code{path} with
#' each value record terminated by a newline.
#'
#' The use-case driving this function is exporting the value side of
#' Project Sonar mtbl files since it would help in processing \code{jq}
#' pipelines.
#'
#' @param x an mtbl file opened with \code{read_mtbl()}
#' @param path full path to output file
#' @export
#' @examples
#' mtbl <- read_mtbl(system.file("extdata/sample.mtbl", package="mtblr"))
#' mtbl_export(mtbl, tempfile())
mtbl_export_values <- function(x, path) {
    invisible(.Call('mtblr_mtbl_export_values', PACKAGE = 'mtblr', x, path))
}

#' Retrieve a key/value pair from an mtbl by key
#'
#' In theory there are no duplicates, but this still
#' returs an iterator that you'll need to use \code{mtbl_next()} with.
#'
#' @param x an mtbl file opened with \code{read_mtbl()}
#' @param key string (exact) to look for in the keys
#' @export
#' @examples
#' mtbl <- read_mtbl(system.file("extdata/sample.mtbl", package="mtblr"))
#' mtbl_next(mtbl_get(mtbl, "aa"))
mtbl_get <- function(x, key) {
    .Call('mtblr_mtbl_get', PACKAGE = 'mtblr', x, key)
}

#' Retrieve value(s) for a given key in an mtbl
#'
#' @param x an mtbl file opened with \code{read_mtbl()}
#' @param key string (prefix) to look for in the keys
#' @export
#' @examples
#' mtbl <- read_mtbl(system.file("extdata/sample.mtbl", package="mtblr"))
#' mtbl_next(mtbl_get_prefix(mtbl, "a"))
mtbl_get_prefix <- function(x, key) {
    .Call('mtblr_mtbl_get_prefix', PACKAGE = 'mtblr', x, key)
}

#' Close an iterator when finished
#'
#' Frees up memory.
#'
#' @param x an open iterator
#' @export
mtbl_iter_close <- function(x) {
    invisible(.Call('mtblr_mtbl_iter_close', PACKAGE = 'mtblr', x))
}

#' Close an mtbl file
#'
#' Will be really useful if we ever implement the write components of the API.
#'
#' @param x an open mtbl file handle
#' @export
close_mtbl <- function(x) {
    invisible(.Call('mtblr_close_mtbl', PACKAGE = 'mtblr', x))
}