R: Hybrid Index, coercion to

as.hi {ff} | R Documentation

## Hybrid Index, coercion to

### Description

The generic `as.hi` and its methods are the main (internal) means for preprocessing index information into the hybrid index class `hi`. Usually `as.hi` is called transparently from `[.ff`. However, you can explicitely do the index-preprocessing, store the Hybrid Index `hi`, and use the `hi` for subscripting.

### Usage

    as.hi(x, ...)
    ## S3 method for class 'hi'
    as.hi(x, ...)
    ## S3 method for class 'ri'
    as.hi(x, maxindex = length(x), ...)
    ## S3 method for class 'bit'
    as.hi(x, range = NULL, maxindex = length(x), vw = NULL
    , dim = NULL, dimorder = NULL, pack = TRUE, ...)
    ## S3 method for class 'bitwhich'
    as.hi(x, maxindex = length(x), pack = FALSE, ...)
    ## S3 method for class 'call'
    as.hi(x, maxindex = NA, dim = NULL, dimorder = NULL, vw = NULL
    , vw.convert = TRUE, pack = TRUE, envir = parent.frame(), ...)
    ## S3 method for class 'name'
    as.hi(x, envir = parent.frame(), ...)

    ## S3 method for class 'integer'
    as.hi(x, maxindex = NA, dim = NULL, dimorder = NULL
    , symmetric = FALSE, fixdiag = NULL, vw = NULL, vw.convert = TRUE
    , dimorder.convert  = TRUE, pack = TRUE, NAs = NULL, ...)
    ## S3 method for class 'which'
    as.hi(x, ...)
    ## S3 method for class 'double'
    as.hi(x, ...)
    ## S3 method for class 'logical'
    as.hi(x, maxindex = NA, dim = NULL, vw = NULL, pack = TRUE, ...)
    ## S3 method for class 'character'
    as.hi(x, names, vw = NULL, vw.convert = TRUE, ...)
    ## S3 method for class 'matrix'
    as.hi(x, dim, dimorder = NULL, symmetric = FALSE, fixdiag = NULL
    , vw = NULL, pack = TRUE, ...)

### Arguments

`x` | an appropriate object of the class for which we dispatched
`envir` | the environment in which to evaluate components of the index expression
`maxindex` | maximum positive indexposition `maxindex`, is needed with negative indices, if vw or dim is given, maxindex is calculated automatically
`names` | the `names` of the indexed vector for character indexing
`dim` | the `dim` of the indexed matrix to be stored within the `hi` object
`dimorder` | the `dimorder` of the indexed matrix to be stored within the `hi` object, may convert interpretation of `x`
`symmetric` | the `symmetric` of the indexed matrix to be stored within the `hi` object
`fixdiag` | the `fixdiag` of the indexed matrix to be stored within the `hi` object
`vw` | the virtual window `vw` of the indexed vector or matrix to be stored within the `hi` object, see details
`vw.convert` | FALSE to prevent doubly virtual window conversion, this is needed for some internal calls that have done the virtual window conversion already, see details
`dimorder.convert` | FALSE to prevent doubly dimorder conversion, this is needed for some internal calls that have done the dimorder conversion already, see details
`NAs` | a vector of NA positions to be stored `rlepacked`, not fully supported yet
`pack` | FALSE to prevent `rlepacking`, note that this is a hint rather than a guarantee, `as.hi.bit` might ignore this
`range` | NULL or a vector with two elements indicating first and last position to be converted from 'bit' to 'hi'
`...` | further argument passed from generic to method or from wrapper method to `as.hi.integer`

### Details

The generic dispatches appropriately, `as.hi.hi` returns an `hi` object unchanged, `as.hi.call` tries to `hiparse` instead of evaluate its input in order to save RAM. If parsing is successfull `as.hi.call` will ignore its argument `pack` and always pack unless the subscript is too small to do so. If parsing fails it evaluates the index expression and dispatches again to one of the other methods. `as.hi.name` and `as.hi.(` are wrappers to `as.hi.call`. `as.hi.integer` is the workhorse for coercing evaluated expressions and `as.hi.which` is a wrapper removing the `which` class attribute. `as.hi.double`, `as.hi.logical` and `as.hi.character` are also wrappers to `as.hi.integer`, but note that `as.hi.logical` is not memory efficient because it expands all positions and then applies logical subscripting.
`as.hi.matrix` calls `arrayIndex2vectorIndex` and then `as.hi.integer` to interpret and preprocess matrix indices.
If the `dim` and `dimorder` parameter indicate a non-standard dimorder (`dimorderStandard`), the index information in `x` is converted from a standard dimorder interpretation to the requested `dimorder`.
If the `vw` parameter is used, the index information in `x` is interpreted relative to the virtual window but stored relative to the abolute origin. Back-coercion via `as.integer.hi` and friends will again return the index information relative to the virtual window, thus retaining symmetry and transparency of the viurtual window to the user.
You can use `length` to query the index length (possibly length of negative subscripts), `poslength` to query the number of selected elements (even with negative subscripts), and `maxindex` to query the largest possible index position (within virtual window, if present)
Duplicated negative indices are removed and will not be recovered by `as.integer.hi`.

### Value

an object of class `hi`

### Note

Avoid changing the Hybrid Index representation, this might crash the `[.ff` subscripting.

### Author(s)

Jens Oehlschlägel

### See Also

`hi` for the Hybrid Index class, `hiparse` for parsing details, `as.integer.hi` for back-coercion, `[.ff` for ff subscripting

### Examples

      message("integer indexing with and without rel-packing")
      as.hi(1:12)
      as.hi(1:12, pack=FALSE)
      message("if index is double, the wrapper method just converts to integer")
      as.hi(as.double(1:12))
      message("if index is character, the wrapper method just converts to integer")
      as.hi(c("a","b","c"), names=letters)
      message("negative index must use maxindex (or vw)")
      as.hi(-(1:3), maxindex=12)
      message("logical index can use maxindex")
      as.hi(c(FALSE, FALSE, TRUE, TRUE))
      as.hi(c(FALSE, FALSE, TRUE, TRUE), maxindex=12)

      message("matrix index")
      x <- matrix(1:12, 6)
      as.hi(rbind(c(1,1), c(1,2), c(2,1)), dim=dim(x))

      message("first ten positions within virtual window")
      i <- as.hi(1:10, vw=c(10, 80, 10))
      i
      message("back-coerce relativ to virtual window")
      as.integer(i)
      message("back-coerce relativ to absolute origin")
      as.integer(i, vw.convert=FALSE)

      message("parsed index expressions save index RAM")
        as.hi(quote(1:1000000000))
    ## Not run:
      message("compare to RAM requirement when the index experssion is evaluated")
        as.hi(1:1000000000)

    ## End(Not run)

    message("example of parsable index expression")
      a <- seq(100, 200, 20)
      as.hi(substitute(c(1:5, 4:9, a)))
      hi(c(1,4, 100),c(5,9, 200), by=c(1,1,20))

    message("two examples of index expression temporarily expanded to full length due to
    non-supported use of brackets '(' and mathematical operators '+' accepting token")
    message("example1: accepted token but aborted parsing because length>16")
      as.hi(quote(1+(1:16)))
    message("example1: rejected token and aborted parsing because length>16")
      as.hi(quote(1+(1:17)))

[Package ff version 2.2-13 Index]