stri_compare {stringi} | R Documentation

## Compare Strings with or without Collation

### Description

These functions may be used to determine if two strings are equal, canonically equivalent (this is performed in a much more clever fashion than when testing for equality), or to check whether they appear in a specific lexicographic order.

### Usage

    stri_compare(e1, e2, ..., opts_collator = NULL)

    stri_cmp(e1, e2, ..., opts_collator = NULL)

    stri_cmp_eq(e1, e2)

    stri_cmp_neq(e1, e2)

    stri_cmp_equiv(e1, e2, ..., opts_collator = NULL)

    stri_cmp_nequiv(e1, e2, ..., opts_collator = NULL)

    stri_cmp_lt(e1, e2, ..., opts_collator = NULL)

    stri_cmp_gt(e1, e2, ..., opts_collator = NULL)

    stri_cmp_le(e1, e2, ..., opts_collator = NULL)

    stri_cmp_ge(e1, e2, ..., opts_collator = NULL)

### Arguments

`e1, e2` | character vectors or objects coercible to character vectors
`...` | additional settings for `opts_collator`
`opts_collator` | a named list with ICU Collator's options as generated with `stri_opts_collator`, `NULL` for default collation options.

### Details

All the functions listed here are vectorized over `e1` and `e2`.

`stri_cmp_eq` tests whether two corresponding strings consist of exactly the same code points, while `stri_cmp_neq` allow to check whether there is any difference between them. These are locale-independent operations: for natural language text processing, in which the notion of canonical equivalence is more valid, this might not be exactly what you are looking for, see Examples. By the way, note that stringi always silently removes UTF-8 BOMs from input strings, so e.g. `stri_cmp_eq` does not take BOMs into account while comparing strings.

On the other hand, `stri_cmp_equiv` tests for canonical equivalence of two strings and is locale-dependent. Additionally, the ICU's Collator may be tuned up so that e.g. the comparison is case-insensitive. To test whether two strings are not canonically equivalent, call `stri_cmp_nequiv`.

What is more, `stri_cmp_le` tests whether the elements in the first vector are less than or equal to the corresponding elements in the second vector, `stri_cmp_ge` tests whether they are greater or equal, `stri_cmp_lt` if less, and `stri_cmp_gt` if greater, see also e.g. `%s<%`.

Finally, `stri_compare` is an alias to `stri_cmp`. They both perform exactly the same locale-dependent operation. Both functions provide a C library's `strcmp()` look-and-feel, see Value for details.

For more information on ICU's Collator and how to tune it up in stringi, refer to `stri_opts_collator`. Please note that different locale settings may lead to different results (see the examples below).

### Value

The `stri_cmp` and `stri_compare` functions return an integer vector with comparison results of corresponding pairs of elements in `e1` and `e2`: `-1` if `e1[...] < e2[...]`, `0` if they are canonically equivalent, and `1` if greater.

The other functions return a logical vector that indicates whether a given relation holds between two corresponding elements in `e1` and `e2`.

### References

Collation - ICU User Guide, http://userguide.icu-project.org/collation

### See Also

Other locale_sensitive: `%s<%`, `stri_count_boundaries`, `stri_duplicated`, `stri_enc_detect2`, `stri_extract_all_boundaries`, `stri_locate_all_boundaries`, `stri_opts_collator`, `stri_order`, `stri_split_boundaries`, `stri_trans_tolower`, `stri_unique`, `stri_wrap`, `stringi-locale`, `stringi-search-boundaries`, `stringi-search-coll`

### Examples

    # in Polish ch < h:
    stri_cmp_lt("hladny", "chladny", locale="pl_PL")

    # in Slovak ch > h:
    stri_cmp_lt("hladny", "chladny", locale="sk_SK")

    # < or > (depends on locale):
    stri_cmp("hladny", "chladny")

    # ignore case differences:
    stri_cmp_equiv("hladny", "HLADNY", strength=2)

    # also ignore diacritical differences:
    stri_cmp_equiv("hladn\u00FD", "hladny", strength=1, locale="sk_SK")

    # non-Unicode-normalized vs normalized string:
    stri_cmp_equiv(stri_trans_nfkd("\u0105"), "\u105")

    # note the difference:
    stri_cmp_eq(stri_trans_nfkd("\u0105"), "\u105")

    # ligatures:
    stri_cmp_equiv("\ufb00", "ff", strength=2)

    # phonebook collation
    stri_cmp_equiv("G\u00e4rtner", "Gaertner", locale="de_DE@collation=phonebook", strength=1L)
    stri_cmp_equiv("G\u00e4rtner", "Gaertner", locale="de_DE", strength=1L)

[Package stringi version 1.1.1 Index]