tuple_split 0.2.2

An extension for the tupleops crate which adds a trait for splitting tuples.
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
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126

[![Build Status (nightly)](https://github.com/sigurd4/tuple_split/workflows/Build-nightly/badge.svg)](https://github.com/sigurd4/tuple_split/actions/workflows/build-nightly.yml)
[![Build Status (nightly, all features)](https://github.com/sigurd4/tuple_split/workflows/Build-nightly-all-features/badge.svg)](https://github.com/sigurd4/tuple_split/actions/workflows/build-nightly-all-features.yml)

[![Build Status (stable)](https://github.com/sigurd4/tuple_split/workflows/Build-stable/badge.svg)](https://github.com/sigurd4/tuple_split/actions/workflows/build-stable.yml)
[![Build Status (stable, all features)](https://github.com/sigurd4/tuple_split/workflows/Build-stable-all-features/badge.svg)](https://github.com/sigurd4/tuple_split/actions/workflows/build-stable-all-features.yml)

[![Test Status](https://github.com/sigurd4/tuple_split/workflows/Test/badge.svg)](https://github.com/sigurd4/tuple_split/actions/workflows/test.yml)
[![Lint Status](https://github.com/sigurd4/tuple_split/workflows/Lint/badge.svg)](https://github.com/sigurd4/tuple_split/actions/workflows/lint.yml)

[![Latest Version](https://img.shields.io/crates/v/tuple_split.svg)](https://crates.io/crates/tuple_split)
[![License:MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Documentation](https://img.shields.io/docsrs/tuple_split)](https://docs.rs/tuple_split)
[![Coverage Status](https://img.shields.io/codecov/c/github/sigurd4/tuple_split)](https://app.codecov.io/github/sigurd4/tuple_split)

# tuple_split

This crate an extension for the [tupleops](https://crates.io/crates/tupleops) crate.

[tupleops](https://crates.io/crates/tupleops) contains many useful features for manipulating tuples and using tuples in generic code. However, it does not support any kind of splitting of tuples. This crate adds that feature.

## Examples

```rust
let t = (32, 0.707, "test");

// Splitting tuples by index
let (l, r) = tuple_split::split_tuple_at::<0, _>(t);
assert_eq!(t, tupleops::concat_tuples(l, r));

let (l, r) = tuple_split::split_tuple_at::<1, _>(t);
assert_eq!(t, tupleops::concat_tuples(l, r));

let (l, r) = tuple_split::split_tuple_at::<2, _>(t);
assert_eq!(t, tupleops::concat_tuples(l, r));

let (l, r) = tuple_split::split_tuple_at::<3, _>(t);
assert_eq!(t, tupleops::concat_tuples(l, r));

// Splitting tuples given a left side
let (l, r) = tuple_split::split_tuple_into_left::<(u8, f32), _>(t);
assert_eq!(t, tupleops::concat_tuples(l, r));

// Splitting tuples given a right side
let (l, r) = tuple_split::split_tuple_into_right::<(&str,), _>(t);
assert_eq!(t, tupleops::concat_tuples(l, r));

// Splitting tuples given both sides
let (l, r) = tuple_split::split_tuple_into::<(u8, f32), (&str)>(t);
assert_eq!(t, tupleops::concat_tuples(l, r));
```

## Split by index

Tuples can be split by a const-generic index. To use this feature, put `#![feature(generic_const_exprs)]` on the top of your `lib.rs` or `main.rs`.

### Example

```rust
#![feature(generic_const_exprs)]

let t = (1, 1.0, "test");

let (l, r) = tuple_split::split_tuple_at::<2, _>(t);

assert_eq!(t, tupleops::concat_tuples(l, r));
```

## Split by type

The type of tuple you want from the split operation can be used instead of an index. This does not require `#![feature(generic_const_exprs)]`. Either the left, right or both can be provided as a generic type.

### Examples

#### Left

```rust
let t = (1, 1.0, "test");

let (l, r) = tuple_split::split_tuple_into_left::<(u8, f32), _>(t);

assert_eq!(t, tupleops::concat_tuples(l, r));
```

#### Right

```rust
let t = (1, 1.0, "test");

let (l, r) = tuple_split::split_tuple_into_right::<(&str,), _>(t);

assert_eq!(t, tupleops::concat_tuples(l, r));
```

#### Both

```rust
let t = (1, 1.0, "test");

let (l, r) = tuple_split::split_tuple_into::<(u8, f32), (&str,)>(t);

assert_eq!(t, tupleops::concat_tuples(l, r));
```

## Tuple sizes

By default, this crate operates with tuples of up to 4 elements, just like the [tupleops](https://crates.io/crates/tupleops) crate. If you need to use bigger tuples, use the features `8`, `16`, `32`, `64`, `96`, `128`, `160`, `192`, `224` or `256` to set the maximum supported tuple size.

If you are using this crate in another crate, it's a nice gesture to provide this tuple size interface to the end user upstream as well. It can be done like this in the `Cargo.toml`:

```toml
[features]
default = []
dont_hurt_yourself_by_using_all_features = ["tuple_split/dont_hurt_yourself_by_using_all_features"]
8 = ["tuple_split/8"]
16 = ["8", "tuple_split/16"]
32 = ["16", "tuple_split/32"]
64 = ["32", "tuple_split/64"]
96 = ["64", "tuple_split/96"]
128 = ["96", "tuple_split/128"]
160 = ["128", "tuple_split/160"]
192 = ["160", "tuple_split/192"]
224 = ["192", "tuple_split/224"]
256 = ["224", "tuple_split/256"]
```

The `dont_hurt_yourself_by_using_all_features` is there to prevent usage of tuples bigger than 8 if `cargo` is ran with the flag `--all-features`. Using a tuple size above 16 is highly discouraged as it will make compilation time unbearably long. Compilation time will increase exponentially. You have been warned.