README-crates.io.md
1The enum `Either` with variants `Left` and `Right` is a general purpose
2sum type with two cases.
3
4Either has methods that are similar to Option and Result, and it also implements
5traits like `Iterator`.
6
7Includes macros `try_left!()` and `try_right!()` to use for
8short-circuiting logic, similar to how the `?` operator is used with `Result`.
9Note that `Either` is general purpose. For describing success or error, use the
10regular `Result`.
11
1
2Either
3======
4
5The enum ``Either`` with variants ``Left`` and ``Right`` and trait
6implementations including Iterator, Read, Write.
7
8Either has methods that are similar to Option and Result.
9
10Includes convenience macros ``try_left!()`` and ``try_right!()`` to use for
11short-circuiting logic.
12
13Please read the `API documentation here`__
14
15__ https://docs.rs/either/
16
17|build_status|_ |crates|_
18
19.. |build_status| image:: https://github.com/rayon-rs/either/workflows/CI/badge.svg?branch=main
20.. _build_status: https://github.com/rayon-rs/either/actions
21
22.. |crates| image:: https://img.shields.io/crates/v/either.svg
23.. _crates: https://crates.io/crates/either
24
25How to use with cargo::
26
27 [dependencies]
28 either = "1"
29
30
31Recent Changes
32--------------
33
34- 1.15.0
35
36 - Fix ``serde`` support when building without ``std``, by @klkvr (#119)
37
38 - Use a more common ``std`` feature for default enablement, deprecating
39 the ``use_std`` feature as a mere alias of the new name.
40
41- 1.14.0
42
43 - **MSRV**: ``either`` now requires Rust 1.63 or later.
44
45 - Implement ``fmt::Write`` for ``Either``, by @yotamofek (#113)
46
47 - Replace ``Into<Result> for Either`` with ``From<Either> for Result``, by @cuviper (#118)
48
49- 1.13.0
50
51 - Add new methods ``.cloned()`` and ``.copied()``, by @ColonelThirtyTwo (#107)
52
53- 1.12.0
54
55 - **MSRV**: ``either`` now requires Rust 1.37 or later.
56
57 - Specialize ``nth_back`` for ``Either`` and ``IterEither``, by @cuviper (#106)
58
59- 1.11.0
60
61 - Add new trait ``IntoEither`` that is useful to convert to ``Either`` in method chains,
62 by @SFM61319 (#101)
63
64- 1.10.0
65
66 - Add new methods ``.factor_iter()``, ``.factor_iter_mut()``, and ``.factor_into_iter()``
67 that return ``Either`` items, plus ``.iter()`` and ``.iter_mut()`` to convert to direct
68 reference iterators; by @aj-bagwell and @cuviper (#91)
69
70- 1.9.0
71
72 - Add new methods ``.map_either()`` and ``.map_either_with()``, by @nasadorian (#82)
73
74- 1.8.1
75
76 - Clarified that the multiple licenses are combined with OR.
77
78- 1.8.0
79
80 - **MSRV**: ``either`` now requires Rust 1.36 or later.
81
82 - Add new methods ``.as_pin_ref()`` and ``.as_pin_mut()`` to project a
83 pinned ``Either`` as inner ``Pin`` variants, by @cuviper (#77)
84
85 - Implement the ``Future`` trait, by @cuviper (#77)
86
87 - Specialize more methods of the ``io`` traits, by @Kixunil and @cuviper (#75)
88
89- 1.7.0
90
91 - **MSRV**: ``either`` now requires Rust 1.31 or later.
92
93 - Export the macro ``for_both!``, by @thomaseizinger (#58)
94
95 - Implement the ``io::Seek`` trait, by @Kerollmops (#60)
96
97 - Add new method ``.either_into()`` for ``Into`` conversion, by @TonalidadeHidrica (#63)
98
99 - Add new methods ``.factor_ok()``, ``.factor_err()``, and ``.factor_none()``,
100 by @zachs18 (#67)
101
102 - Specialize ``source`` in the ``Error`` implementation, by @thomaseizinger (#69)
103
104 - Specialize more iterator methods and implement the ``FusedIterator`` trait,
105 by @Ten0 (#66) and @cuviper (#71)
106
107 - Specialize ``Clone::clone_from``, by @cuviper (#72)
108
109- 1.6.1
110
111 - Add new methods ``.expect_left()``, ``.unwrap_left()``,
112 and equivalents on the right, by @spenserblack (#51)
113
114- 1.6.0
115
116 - Add new modules ``serde_untagged`` and ``serde_untagged_optional`` to customize
117 how ``Either`` fields are serialized in other types, by @MikailBag (#49)
118
119- 1.5.3
120
121 - Add new method ``.map()`` for ``Either<T, T>`` by @nvzqz (#40).
122
123- 1.5.2
124
125 - Add new methods ``.left_or()``, ``.left_or_default()``, ``.left_or_else()``,
126 and equivalents on the right, by @DCjanus (#36)
127
128- 1.5.1
129
130 - Add ``AsRef`` and ``AsMut`` implementations for common unsized types:
131 ``str``, ``[T]``, ``CStr``, ``OsStr``, and ``Path``, by @mexus (#29)
132
133- 1.5.0
134
135 - Add new methods ``.factor_first()``, ``.factor_second()`` and ``.into_inner()``
136 by @mathstuf (#19)
137
138- 1.4.0
139
140 - Add inherent method ``.into_iter()`` by @cuviper (#12)
141
142- 1.3.0
143
144 - Add opt-in serde support by @hcpl
145
146- 1.2.0
147
148 - Add method ``.either_with()`` by @Twey (#13)
149
150- 1.1.0
151
152 - Add methods ``left_and_then``, ``right_and_then`` by @rampantmonkey
153 - Include license files in the repository and released crate
154
155- 1.0.3
156
157 - Add crate categories
158
159- 1.0.2
160
161 - Forward more ``Iterator`` methods
162 - Implement ``Extend`` for ``Either<L, R>`` if ``L, R`` do.
163
164- 1.0.1
165
166 - Fix ``Iterator`` impl for ``Either`` to forward ``.fold()``.
167
168- 1.0.0
169
170 - Add default crate feature ``use_std`` so that you can opt out of linking to
171 std.
172
173- 0.1.7
174
175 - Add methods ``.map_left()``, ``.map_right()`` and ``.either()``.
176 - Add more documentation
177
178- 0.1.3
179
180 - Implement Display, Error
181
182- 0.1.2
183
184 - Add macros ``try_left!`` and ``try_right!``.
185
186- 0.1.1
187
188 - Implement Deref, DerefMut
189
190- 0.1.0
191
192 - Initial release
193 - Support Iterator, Read, Write
194
195License
196-------
197
198Dual-licensed to be compatible with the Rust project.
199
200Licensed under the Apache License, Version 2.0
201https://www.apache.org/licenses/LICENSE-2.0 or the MIT license
202https://opensource.org/licenses/MIT, at your
203option. This file may not be copied, modified, or distributed
204except according to those terms.
205
