Skip to content

Commit f1cc7d6

Browse files
author
lukaramu
committed
Revised core::ops::range::* docs
Part of #29365. * Strenghtened summary/explanation split, making phrasings more parallel * Added links throughout * Fixed some example formatting & removed extraneous `fn main()`s (or hid then when needed because of `#![features]`. * Emphasized note on `RangeFrom`'s `Iterator` implementation * Added summary sentences to (unstable) `contains` methods
1 parent 5414c85 commit f1cc7d6

File tree

1 file changed

+120
-95
lines changed

1 file changed

+120
-95
lines changed

src/libcore/ops/range.rs

Lines changed: 120 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,10 @@
1010

1111
use fmt;
1212

13-
/// An unbounded range. Use `..` (two dots) for its shorthand.
13+
/// An unbounded range (`..`).
1414
///
15-
/// Its primary use case is slicing index. It cannot serve as an iterator
16-
/// because it doesn't have a starting point.
15+
/// `RangeFull` is primarily used as a [slicing index], it's shorthand is `..`.
16+
/// It cannot serve as an [`Iterator`] because it doesn't have a starting point.
1717
///
1818
/// # Examples
1919
///
@@ -23,16 +23,16 @@ use fmt;
2323
/// assert_eq!((..), std::ops::RangeFull);
2424
/// ```
2525
///
26-
/// It does not have an `IntoIterator` implementation, so you can't use it in a
27-
/// `for` loop directly. This won't compile:
26+
/// It does not have an [`IntoIterator`] implementation, so you can't use it in
27+
/// a `for` loop directly. This won't compile:
2828
///
2929
/// ```compile_fail,E0277
3030
/// for i in .. {
3131
/// // ...
3232
/// }
3333
/// ```
3434
///
35-
/// Used as a slicing index, `RangeFull` produces the full array as a slice.
35+
/// Used as a [slicing index], `RangeFull` produces the full array as a slice.
3636
///
3737
/// ```
3838
/// let arr = [0, 1, 2, 3];
@@ -41,6 +41,10 @@ use fmt;
4141
/// assert_eq!(arr[1.. ], [ 1,2,3]);
4242
/// assert_eq!(arr[1..3], [ 1,2 ]);
4343
/// ```
44+
///
45+
/// [`IntoIterator`]: ../iter/trait.Iterator.html
46+
/// [`Iterator`]: ../iter/trait.IntoIterator.html
47+
/// [slicing index]: ../slice/trait.SliceIndex.html
4448
#[derive(Copy, Clone, PartialEq, Eq, Hash)]
4549
#[stable(feature = "rust1", since = "1.0.0")]
4650
pub struct RangeFull;
@@ -52,24 +56,23 @@ impl fmt::Debug for RangeFull {
5256
}
5357
}
5458

55-
/// A (half-open) range which is bounded at both ends: { x | start <= x < end }.
56-
/// Use `start..end` (two dots) for its shorthand.
59+
/// A (half-open) range bounded inclusively below and exclusively above
60+
/// (`start..end`).
5761
///
58-
/// See the [`contains`](#method.contains) method for its characterization.
62+
/// The `Range` `start..end` contains all values with `x >= start` and
63+
/// `x < end`.
5964
///
6065
/// # Examples
6166
///
6267
/// ```
63-
/// fn main() {
64-
/// assert_eq!((3..5), std::ops::Range{ start: 3, end: 5 });
65-
/// assert_eq!(3+4+5, (3..6).sum());
66-
///
67-
/// let arr = [0, 1, 2, 3];
68-
/// assert_eq!(arr[ .. ], [0,1,2,3]);
69-
/// assert_eq!(arr[ ..3], [0,1,2 ]);
70-
/// assert_eq!(arr[1.. ], [ 1,2,3]);
71-
/// assert_eq!(arr[1..3], [ 1,2 ]); // Range
72-
/// }
68+
/// assert_eq!((3..5), std::ops::Range { start: 3, end: 5 });
69+
/// assert_eq!(3 + 4 + 5, (3..6).sum());
70+
///
71+
/// let arr = [0, 1, 2, 3];
72+
/// assert_eq!(arr[ .. ], [0,1,2,3]);
73+
/// assert_eq!(arr[ ..3], [0,1,2 ]);
74+
/// assert_eq!(arr[1.. ], [ 1,2,3]);
75+
/// assert_eq!(arr[1..3], [ 1,2 ]); // Range
7376
/// ```
7477
#[derive(Clone, PartialEq, Eq, Hash)] // not Copy -- see #27186
7578
#[stable(feature = "rust1", since = "1.0.0")]
@@ -91,49 +94,51 @@ impl<Idx: fmt::Debug> fmt::Debug for Range<Idx> {
9194

9295
#[unstable(feature = "range_contains", reason = "recently added as per RFC", issue = "32311")]
9396
impl<Idx: PartialOrd<Idx>> Range<Idx> {
97+
/// Returns `true` if `item` is contained in the range.
98+
///
9499
/// # Examples
95100
///
96101
/// ```
97102
/// #![feature(range_contains)]
98-
/// fn main() {
99-
/// assert!( ! (3..5).contains(2));
100-
/// assert!( (3..5).contains(3));
101-
/// assert!( (3..5).contains(4));
102-
/// assert!( ! (3..5).contains(5));
103103
///
104-
/// assert!( ! (3..3).contains(3));
105-
/// assert!( ! (3..2).contains(3));
106-
/// }
104+
/// # fn main() {
105+
/// assert!(!(3..5).contains(2));
106+
/// assert!( (3..5).contains(3));
107+
/// assert!( (3..5).contains(4));
108+
/// assert!(!(3..5).contains(5));
109+
///
110+
/// assert!(!(3..3).contains(3));
111+
/// assert!(!(3..2).contains(3));
112+
/// # }
107113
/// ```
108114
pub fn contains(&self, item: Idx) -> bool {
109115
(self.start <= item) && (item < self.end)
110116
}
111117
}
112118

113-
/// A range which is only bounded below: { x | start <= x }.
114-
/// Use `start..` for its shorthand.
119+
/// A range only bounded inclusively below (`start..`).
115120
///
116-
/// See the [`contains`](#method.contains) method for its characterization.
121+
/// The `RangeFrom` `start..` contains all values with `x >= start`.
117122
///
118-
/// Note: Currently, no overflow checking is done for the iterator
123+
/// *Note*: Currently, no overflow checking is done for the [`Iterator`]
119124
/// implementation; if you use an integer range and the integer overflows, it
120-
/// might panic in debug mode or create an endless loop in release mode. This
121-
/// overflow behavior might change in the future.
125+
/// might panic in debug mode or create an endless loop in release mode. **This
126+
/// overflow behavior might change in the future.**
122127
///
123128
/// # Examples
124129
///
125130
/// ```
126-
/// fn main() {
127-
/// assert_eq!((2..), std::ops::RangeFrom{ start: 2 });
128-
/// assert_eq!(2+3+4, (2..).take(3).sum());
129-
///
130-
/// let arr = [0, 1, 2, 3];
131-
/// assert_eq!(arr[ .. ], [0,1,2,3]);
132-
/// assert_eq!(arr[ ..3], [0,1,2 ]);
133-
/// assert_eq!(arr[1.. ], [ 1,2,3]); // RangeFrom
134-
/// assert_eq!(arr[1..3], [ 1,2 ]);
135-
/// }
131+
/// assert_eq!((2..), std::ops::RangeFrom { start: 2 });
132+
/// assert_eq!(2 + 3 + 4, (2..).take(3).sum());
133+
///
134+
/// let arr = [0, 1, 2, 3];
135+
/// assert_eq!(arr[ .. ], [0,1,2,3]);
136+
/// assert_eq!(arr[ ..3], [0,1,2 ]);
137+
/// assert_eq!(arr[1.. ], [ 1,2,3]); // RangeFrom
138+
/// assert_eq!(arr[1..3], [ 1,2 ]);
136139
/// ```
140+
///
141+
/// [`Iterator`]: ../iter/trait.IntoIterator.html
137142
#[derive(Clone, PartialEq, Eq, Hash)] // not Copy -- see #27186
138143
#[stable(feature = "rust1", since = "1.0.0")]
139144
pub struct RangeFrom<Idx> {
@@ -151,46 +156,47 @@ impl<Idx: fmt::Debug> fmt::Debug for RangeFrom<Idx> {
151156

152157
#[unstable(feature = "range_contains", reason = "recently added as per RFC", issue = "32311")]
153158
impl<Idx: PartialOrd<Idx>> RangeFrom<Idx> {
159+
/// Returns `true` if `item` is contained in the range.
160+
///
154161
/// # Examples
155162
///
156163
/// ```
157164
/// #![feature(range_contains)]
158-
/// fn main() {
159-
/// assert!( ! (3..).contains(2));
160-
/// assert!( (3..).contains(3));
161-
/// assert!( (3..).contains(1_000_000_000));
162-
/// }
165+
///
166+
/// # fn main() {
167+
/// assert!(!(3..).contains(2));
168+
/// assert!( (3..).contains(3));
169+
/// assert!( (3..).contains(1_000_000_000));
170+
/// # }
163171
/// ```
164172
pub fn contains(&self, item: Idx) -> bool {
165173
(self.start <= item)
166174
}
167175
}
168176

169-
/// A range which is only bounded above: { x | x < end }.
170-
/// Use `..end` (two dots) for its shorthand.
171-
///
172-
/// See the [`contains`](#method.contains) method for its characterization.
177+
/// A range only bounded exclusively above (`..end`).
173178
///
174-
/// It cannot serve as an iterator because it doesn't have a starting point.
179+
/// The `RangeTo` `..end` contains all values with `x < end`.
180+
/// It cannot serve as an [`Iterator`] because it doesn't have a starting point.
175181
///
176182
/// # Examples
177183
///
178-
/// The `..{integer}` syntax is a `RangeTo`:
184+
/// The `..end` syntax is a `RangeTo`:
179185
///
180186
/// ```
181-
/// assert_eq!((..5), std::ops::RangeTo{ end: 5 });
187+
/// assert_eq!((..5), std::ops::RangeTo { end: 5 });
182188
/// ```
183189
///
184-
/// It does not have an `IntoIterator` implementation, so you can't use it in a
185-
/// `for` loop directly. This won't compile:
190+
/// It does not have an [`IntoIterator`] implementation, so you can't use it in
191+
/// a `for` loop directly. This won't compile:
186192
///
187193
/// ```compile_fail,E0277
188194
/// for i in ..5 {
189195
/// // ...
190196
/// }
191197
/// ```
192198
///
193-
/// When used as a slicing index, `RangeTo` produces a slice of all array
199+
/// When used as a [slicing index], `RangeTo` produces a slice of all array
194200
/// elements before the index indicated by `end`.
195201
///
196202
/// ```
@@ -200,6 +206,10 @@ impl<Idx: PartialOrd<Idx>> RangeFrom<Idx> {
200206
/// assert_eq!(arr[1.. ], [ 1,2,3]);
201207
/// assert_eq!(arr[1..3], [ 1,2 ]);
202208
/// ```
209+
///
210+
/// [`IntoIterator`]: ../iter/trait.Iterator.html
211+
/// [`Iterator`]: ../iter/trait.IntoIterator.html
212+
/// [slicing index]: ../slice/trait.SliceIndex.html
203213
#[derive(Copy, Clone, PartialEq, Eq, Hash)]
204214
#[stable(feature = "rust1", since = "1.0.0")]
205215
pub struct RangeTo<Idx> {
@@ -217,38 +227,42 @@ impl<Idx: fmt::Debug> fmt::Debug for RangeTo<Idx> {
217227

218228
#[unstable(feature = "range_contains", reason = "recently added as per RFC", issue = "32311")]
219229
impl<Idx: PartialOrd<Idx>> RangeTo<Idx> {
230+
/// Returns `true` if `item` is contained in the range.
231+
///
220232
/// # Examples
221233
///
222234
/// ```
223235
/// #![feature(range_contains)]
224-
/// fn main() {
225-
/// assert!( (..5).contains(-1_000_000_000));
226-
/// assert!( (..5).contains(4));
227-
/// assert!( ! (..5).contains(5));
228-
/// }
236+
///
237+
/// # fn main() {
238+
/// assert!( (..5).contains(-1_000_000_000));
239+
/// assert!( (..5).contains(4));
240+
/// assert!(!(..5).contains(5));
241+
/// # }
229242
/// ```
230243
pub fn contains(&self, item: Idx) -> bool {
231244
(item < self.end)
232245
}
233246
}
234247

235-
/// An inclusive range which is bounded at both ends: { x | start <= x <= end }.
236-
/// Use `start...end` (three dots) for its shorthand.
248+
/// An range bounded inclusively below and above (`start...end`).
237249
///
238-
/// See the [`contains`](#method.contains) method for its characterization.
250+
/// The `RangeInclusive` `start...end` contains all values with `x >= start`
251+
/// and `x <= end`.
239252
///
240253
/// # Examples
241254
///
242255
/// ```
243256
/// #![feature(inclusive_range,inclusive_range_syntax)]
244-
/// fn main() {
245-
/// assert_eq!((3...5), std::ops::RangeInclusive{ start: 3, end: 5 });
246-
/// assert_eq!(3+4+5, (3...5).sum());
247257
///
248-
/// let arr = [0, 1, 2, 3];
249-
/// assert_eq!(arr[ ...2], [0,1,2 ]);
250-
/// assert_eq!(arr[1...2], [ 1,2 ]); // RangeInclusive
251-
/// }
258+
/// # fn main() {
259+
/// assert_eq!((3...5), std::ops::RangeInclusive { start: 3, end: 5 });
260+
/// assert_eq!(3 + 4 + 5, (3...5).sum());
261+
///
262+
/// let arr = [0, 1, 2, 3];
263+
/// assert_eq!(arr[ ...2], [0,1,2 ]);
264+
/// assert_eq!(arr[1...2], [ 1,2 ]); // RangeInclusive
265+
/// # }
252266
/// ```
253267
#[derive(Clone, PartialEq, Eq, Hash)] // not Copy -- see #27186
254268
#[unstable(feature = "inclusive_range", reason = "recently added, follows RFC", issue = "28237")]
@@ -274,43 +288,44 @@ impl<Idx: fmt::Debug> fmt::Debug for RangeInclusive<Idx> {
274288

275289
#[unstable(feature = "range_contains", reason = "recently added as per RFC", issue = "32311")]
276290
impl<Idx: PartialOrd<Idx>> RangeInclusive<Idx> {
291+
/// Returns `true` if `item` is contained in the range.
292+
///
277293
/// # Examples
278294
///
279295
/// ```
280296
/// #![feature(range_contains,inclusive_range_syntax)]
281-
/// fn main() {
282-
/// assert!( ! (3...5).contains(2));
283-
/// assert!( (3...5).contains(3));
284-
/// assert!( (3...5).contains(4));
285-
/// assert!( (3...5).contains(5));
286-
/// assert!( ! (3...5).contains(6));
287297
///
288-
/// assert!( (3...3).contains(3));
289-
/// assert!( ! (3...2).contains(3));
290-
/// }
298+
/// # fn main() {
299+
/// assert!(!(3...5).contains(2));
300+
/// assert!( (3...5).contains(3));
301+
/// assert!( (3...5).contains(4));
302+
/// assert!( (3...5).contains(5));
303+
/// assert!(!(3...5).contains(6));
304+
///
305+
/// assert!( (3...3).contains(3));
306+
/// assert!(!(3...2).contains(3));
307+
/// # }
291308
/// ```
292309
pub fn contains(&self, item: Idx) -> bool {
293310
self.start <= item && item <= self.end
294311
}
295312
}
296313

297-
/// An inclusive range which is only bounded above: { x | x <= end }.
298-
/// Use `...end` (three dots) for its shorthand.
299-
///
300-
/// See the [`contains`](#method.contains) method for its characterization.
314+
/// A range only bounded inclusively above (`...end`).
301315
///
302-
/// It cannot serve as an iterator because it doesn't have a starting point.
316+
/// The `RangeToInclusive` `...end` contains all values with `x <= end`.
317+
/// It cannot serve as an [`Iterator`] because it doesn't have a starting point.
303318
///
304319
/// # Examples
305320
///
306-
/// The `...{integer}` syntax is a `RangeToInclusive`:
321+
/// The `...end` syntax is a `RangeToInclusive`:
307322
///
308323
/// ```
309324
/// #![feature(inclusive_range,inclusive_range_syntax)]
310325
/// assert_eq!((...5), std::ops::RangeToInclusive{ end: 5 });
311326
/// ```
312327
///
313-
/// It does not have an `IntoIterator` implementation, so you can't use it in a
328+
/// It does not have an [`IntoIterator`] implementation, so you can't use it in a
314329
/// `for` loop directly. This won't compile:
315330
///
316331
/// ```compile_fail,E0277
@@ -320,15 +335,22 @@ impl<Idx: PartialOrd<Idx>> RangeInclusive<Idx> {
320335
/// }
321336
/// ```
322337
///
323-
/// When used as a slicing index, `RangeToInclusive` produces a slice of all
338+
/// When used as a [slicing index], `RangeToInclusive` produces a slice of all
324339
/// array elements up to and including the index indicated by `end`.
325340
///
326341
/// ```
327342
/// #![feature(inclusive_range_syntax)]
343+
///
344+
/// # fn main() {
328345
/// let arr = [0, 1, 2, 3];
329346
/// assert_eq!(arr[ ...2], [0,1,2 ]); // RangeToInclusive
330347
/// assert_eq!(arr[1...2], [ 1,2 ]);
348+
/// # }
331349
/// ```
350+
///
351+
/// [`IntoIterator`]: ../iter/trait.Iterator.html
352+
/// [`Iterator`]: ../iter/trait.IntoIterator.html
353+
/// [slicing index]: ../slice/trait.SliceIndex.html
332354
#[derive(Copy, Clone, PartialEq, Eq, Hash)]
333355
#[unstable(feature = "inclusive_range", reason = "recently added, follows RFC", issue = "28237")]
334356
pub struct RangeToInclusive<Idx> {
@@ -348,15 +370,18 @@ impl<Idx: fmt::Debug> fmt::Debug for RangeToInclusive<Idx> {
348370

349371
#[unstable(feature = "range_contains", reason = "recently added as per RFC", issue = "32311")]
350372
impl<Idx: PartialOrd<Idx>> RangeToInclusive<Idx> {
373+
/// Returns `true` if `item` is contained in the range.
374+
///
351375
/// # Examples
352376
///
353377
/// ```
354378
/// #![feature(range_contains,inclusive_range_syntax)]
355-
/// fn main() {
356-
/// assert!( (...5).contains(-1_000_000_000));
357-
/// assert!( (...5).contains(5));
358-
/// assert!( ! (...5).contains(6));
359-
/// }
379+
///
380+
/// # fn main() {
381+
/// assert!( (...5).contains(-1_000_000_000));
382+
/// assert!( (...5).contains(5));
383+
/// assert!(!(...5).contains(6));
384+
/// # }
360385
/// ```
361386
pub fn contains(&self, item: Idx) -> bool {
362387
(item <= self.end)

0 commit comments

Comments
 (0)