jetscii 0.3.1

A tiny library to efficiently search strings for substrings or sets of ASCII characters.
Documentation 
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
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

# Jetscii

A tiny library to efficiently search strings for substrings or sets of
ASCII characters.

[![Build Status](https://travis-ci.org/shepmaster/jetscii.svg)](https://travis-ci.org/shepmaster/jetscii) [![Current Version](http://meritbadge.herokuapp.com/jetscii)](https://crates.io/crates/jetscii)

[Documentation](https://shepmaster.github.io/jetscii/)

## Examples

### Searching for a set of ASCII characters

```rust
#[macro_use]
extern crate jetscii;

fn main() {
    let part_number = "86-J52:rev1";
    let parts: Vec<_> = part_number.split(ascii_chars!('-', ':')).collect();
    assert_eq!(&parts, &["86", "J52", "rev1"]);
}
```

### Searching for a substring

```rust
use jetscii::Substring;
let colors: Vec<_> = "red, blue, green".split(Substring::new(", ")).collect();
assert_eq!(&colors, &["red", "blue", "green"]);
```

## What's so special about this library?

We use a particular set of x86-64 SSE 4.2 instructions (`PCMPESTRI`
and `PCMPESTRM`) to gain great speedups. This method stays fast even
when searching for a character in a set of up to 16 choices.

When the `PCMPxSTRx` instructions are not available, we fall back to
reasonably fast but universally-supported methods.

## Benchmarks

### Single character

Searching a 5MiB string of `a`s with a single space at the end:

| Method                                           | Speed     |
|--------------------------------------------------|-----------|
| **`str.find(AsciiChars)`**                       | 5719 MB/s |
| `str.as_bytes().iter().position(|&v| v == b' ')` | 1620 MB/s |
| `str.find(|c| c == ' ')`                         | 1090 MB/s |
| `str.find(' ')`                                  | 1085 MB/s |
| `str.find(&[' '][..])`                           |  602 MB/s |
| `str.find(" ")`                                  |  293 MB/s |

### Set of characters

Searching a 5MiB string of `a`s with a single ampersand at the end:

| Method                                           | Speed     |
|--------------------------------------------------|-----------|
| **`str.find(AsciiChars)`**                       | 5688 MB/s |
| `str.as_bytes().iter().position(|&v| ...)`       | 1620 MB/s |
| `str.find(|c| ...)`                              | 1022 MB/s |
| `str.find(&['<', '>', '&'][..])`                 |  361 MB/s |

### Substrings

| Method                                           | Speed     |
|--------------------------------------------------|-----------|
| **`str.find(Substring::new("xyzzy"))`**          | 5017 MB/s |
| str.find("xyzzy"                                 | 3837 MB/s |

## Contributing

1. Fork it ( https://github.com/shepmaster/jetscii/fork )
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Add a failing test.
4. Add code to pass the test.
5. Commit your changes (`git commit -am 'Add some feature'`)
6. Ensure tests pass.
7. Push to the branch (`git push origin my-new-feature`)
8. Create a new Pull Request