swift-check 0.1.0

High-performance library for expressive searching and validation (uses SIMD on x86_64, aarch64, and WASM)
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
85
86
87
88
89
90

# Swift Check

Swift Check is a high-performance library designed for searching and validating data via expressive conditions.

### Supported Acceleration

- x86_64  (SSE2 and if available SSE4.1)
- aarch64 (NEON)
- WASM    (simd128) (currently requires the `experimental` feature)

### Installation

Add Swift Check to your project by including it in your Cargo.toml:

```toml
[dependencies]
swift-check = "0.1.0"
```

### Quick Start

Using this library is fairly straight forward, `swift-check` exposes various conditions that can be composed with each 
other to create complex and performant searches / validators.

Search for the first comma:
```rust
use swift_check::{search, eq};

fn main() {
    let input = b"hello, world!";
  
    let Some(first_comma) = search(input, eq(b',')) else {
        unreachable!("There's a comma!")
    };

    assert_eq!(input[first_comma], b',');
}
```

Ensure every byte is a character, number, or space:
```rust
use swift_check::{for_all_ensure, any, range, eq};

fn main() {
    let input = b"Hello World 12345";
  
    let res = for_all_ensure(input, any!(
        range!(b'A'..=b'Z'), range!(b'a'..=b'z'),
        range!(b'0'..=b'9'), eq(b' ')
    ));
    assert!(res);
}
```

### Minimum Supported Rust Version

This crate's minimum supported `rustc` version is `1.61.0`

### Contributing

We warmly welcome contributions from the community! If you're interested in helping Swift Check grow and improve, here 
are the areas we're currently focusing on:

- **Expanding the Test Suite**: Ensuring robustness through comprehensive tests is vital. We're looking to expand our 
  test suite to cover more edge cases and usage scenarios.
- **Optimizing the Fallback Implementation**: We aim to optimize our fallback mechanisms to ensure that Swift Check 
  remains efficient even when SIMD is not available / supported. 
- **Optimization**: Once we've solidified our foundational code, we plan to refine our search and validation procedures.

### Note

This library is in its early stages, having started as an exploratory project. We've been delighted to find that our
"what if" scenario is not only possible but promising. Currently, our primary focus is on ensuring that the library
functions correctly, while recognizing that there are several opportunities for optimization in the scanning process.

In our performance evaluations, we discovered that the use of higher-order functions do not adversely affect
performance. We experimented with various implementations, including one where variadic macros created structs to
maintain SIMD registers throughout the search process. This approach performed comparably to our higher-order 
implementation. The main advantage of the struct-based approach is its ability to selectively utilize SIMD; for example,
it enables us to perform simple searches over smaller inputs instead of relying on partial SIMD loads. However, the
trade-off is complexity: adopting this method could require shifting to procedural macros or requiring users to provide
identifiers for each condition in our declarative macros.

### Performance

For massive inputs if you're just searching for a simple needle the `memchr` crate is a better bet. In these
circumstances `memchr` outperforms this crate by ~2x. This is primarily an algorithmic difference, as the higher level
api of this crate as previously acknowledged has much room for optimization, so this gap should be reduced as time goes
on. In general use `memchr` and `swift-check` go back and forth as to who is more performant, for more details run the
benches yourself with `cargo bench`.