# Hits-comparison: Comparing and ordering hits In S4Vectors: S4 implementation of vectors and lists

## Description

`==`, `!=`, `<=`, `>=`, `<`, `>`, `match()`, `%in%`, `order()`, `sort()`, and `rank()` can be used on Hits objects to compare and order hits.

Note that only the `"pcompare"`, `"match"`, and `"order"` methods are actually defined for Hits objects. This is all what is needed to make all the other comparing and ordering operations (i.e. `==`, `!=`, `<=`, `>=`, `<`, `>`, `%in%`, `sort()`, and `rank()`) work on these objects (see `?`Vector-comparison`` for more information about this).

## Usage

 ```1 2 3 4 5 6 7 8 9``` ```## S4 method for signature 'Hits,Hits' pcompare(x, y) ## S4 method for signature 'Hits,Hits' match(x, table, nomatch=NA_integer_, incomparables=NULL, method=c("auto", "quick", "hash")) ## S4 method for signature 'Hits' order(..., na.last=TRUE, decreasing=FALSE, method=c("auto", "shell", "radix")) ```

## Arguments

 `x, y, table` Compatible Hits objects, that is, Hits objects with the same subject and query lengths. `nomatch` The value to be returned in the case when no match is found. It is coerced to an `integer`. `incomparables` Not supported. `method` For `match`: Use a Quicksort-based (`method="quick"`) or a hash-based (`method="hash"`) algorithm. The latter tends to give better performance, except maybe for some pathological input that we've not encountered so far. When `method="auto"` is specified, the most efficient algorithm will be used, that is, the hash-based algorithm if `length(x) <= 2^29`, otherwise the Quicksort-based algorithm. For `order`: The `method` argument is ignored. `...` One or more Hits objects. The additional Hits objects are used to break ties. `na.last` Ignored. `decreasing` `TRUE` or `FALSE`.

## Details

Only hits that belong to Hits objects with same subject and query lengths can be compared.

Hits are ordered by query hit first, and then by subject hit. On a Hits object, `order`, `sort`, and `rank` are consistent with this order.

`pcompare(x, y)`: Performs element-wise (aka "parallel") comparison of 2 Hits objects `x` and `y`, that is, returns an integer vector where the i-th element is less than, equal to, or greater than zero if `x[i]` is considered to be respectively less than, equal to, or greater than `y[i]`. See `?`Vector-comparison`` for how `x` or `y` is recycled when the 2 objects don't have the same length.

`match(x, table, nomatch=NA_integer_, method=c("auto", "quick", "hash"))`: Returns an integer vector of the length of `x`, containing the index of the first matching hit in `table` (or `nomatch` if there is no matching hit) for each hit in `x`.

`order(...)`: Returns a permutation which rearranges its first argument (a Hits object) into ascending order, breaking ties by further arguments (also Hits objects).

## Author(s)

Herv<c3><a9> Pag<c3><a8>s

 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28``` ```## --------------------------------------------------------------------- ## A. ELEMENT-WISE (AKA "PARALLEL") COMPARISON OF 2 Hits OBJECTS ## --------------------------------------------------------------------- hits <- Hits(c(2, 4, 4, 4, 5, 5), c(3, 1, 3, 2, 3, 2), 6, 3) hits pcompare(hits, hits[3]) pcompare(hits[3], hits) hits == hits[3] hits != hits[3] hits >= hits[3] hits < hits[3] ## --------------------------------------------------------------------- ## B. match(), %in% ## --------------------------------------------------------------------- table <- hits[-c(1, 3)] match(hits, table) hits %in% table ## --------------------------------------------------------------------- ## C. order(), sort(), rank() ## --------------------------------------------------------------------- order(hits) sort(hits) rank(hits) ```