10
10
11
11
use fmt;
12
12
13
- /// An unbounded range. Use `..` (two dots) for its shorthand .
13
+ /// An unbounded range ( `..`) .
14
14
///
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.
17
17
///
18
18
/// # Examples
19
19
///
@@ -23,16 +23,16 @@ use fmt;
23
23
/// assert_eq!((..), std::ops::RangeFull);
24
24
/// ```
25
25
///
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:
28
28
///
29
29
/// ```compile_fail,E0277
30
30
/// for i in .. {
31
31
/// // ...
32
32
/// }
33
33
/// ```
34
34
///
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.
36
36
///
37
37
/// ```
38
38
/// let arr = [0, 1, 2, 3];
@@ -41,6 +41,10 @@ use fmt;
41
41
/// assert_eq!(arr[1.. ], [ 1,2,3]);
42
42
/// assert_eq!(arr[1..3], [ 1,2 ]);
43
43
/// ```
44
+ ///
45
+ /// [`IntoIterator`]: ../iter/trait.Iterator.html
46
+ /// [`Iterator`]: ../iter/trait.IntoIterator.html
47
+ /// [slicing index]: ../slice/trait.SliceIndex.html
44
48
#[ derive( Copy , Clone , PartialEq , Eq , Hash ) ]
45
49
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
46
50
pub struct RangeFull ;
@@ -52,24 +56,23 @@ impl fmt::Debug for RangeFull {
52
56
}
53
57
}
54
58
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`) .
57
61
///
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`.
59
64
///
60
65
/// # Examples
61
66
///
62
67
/// ```
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
73
76
/// ```
74
77
#[ derive( Clone , PartialEq , Eq , Hash ) ] // not Copy -- see #27186
75
78
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
@@ -91,49 +94,51 @@ impl<Idx: fmt::Debug> fmt::Debug for Range<Idx> {
91
94
92
95
#[ unstable( feature = "range_contains" , reason = "recently added as per RFC" , issue = "32311" ) ]
93
96
impl < Idx : PartialOrd < Idx > > Range < Idx > {
97
+ /// Returns `true` if `item` is contained in the range.
98
+ ///
94
99
/// # Examples
95
100
///
96
101
/// ```
97
102
/// #![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));
103
103
///
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
+ /// # }
107
113
/// ```
108
114
pub fn contains ( & self , item : Idx ) -> bool {
109
115
( self . start <= item) && ( item < self . end )
110
116
}
111
117
}
112
118
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..`).
115
120
///
116
- /// See the [`contains`](#method. contains) method for its characterization .
121
+ /// The `RangeFrom` `start..` contains all values with `x >= start` .
117
122
///
118
- /// Note: Currently, no overflow checking is done for the iterator
123
+ /// * Note* : Currently, no overflow checking is done for the [`Iterator`]
119
124
/// 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.**
122
127
///
123
128
/// # Examples
124
129
///
125
130
/// ```
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 ]);
136
139
/// ```
140
+ ///
141
+ /// [`Iterator`]: ../iter/trait.IntoIterator.html
137
142
#[ derive( Clone , PartialEq , Eq , Hash ) ] // not Copy -- see #27186
138
143
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
139
144
pub struct RangeFrom < Idx > {
@@ -151,46 +156,47 @@ impl<Idx: fmt::Debug> fmt::Debug for RangeFrom<Idx> {
151
156
152
157
#[ unstable( feature = "range_contains" , reason = "recently added as per RFC" , issue = "32311" ) ]
153
158
impl < Idx : PartialOrd < Idx > > RangeFrom < Idx > {
159
+ /// Returns `true` if `item` is contained in the range.
160
+ ///
154
161
/// # Examples
155
162
///
156
163
/// ```
157
164
/// #![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
+ /// # }
163
171
/// ```
164
172
pub fn contains ( & self , item : Idx ) -> bool {
165
173
( self . start <= item)
166
174
}
167
175
}
168
176
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`).
173
178
///
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.
175
181
///
176
182
/// # Examples
177
183
///
178
- /// The `..{integer} ` syntax is a `RangeTo`:
184
+ /// The `..end ` syntax is a `RangeTo`:
179
185
///
180
186
/// ```
181
- /// assert_eq!((..5), std::ops::RangeTo{ end: 5 });
187
+ /// assert_eq!((..5), std::ops::RangeTo { end: 5 });
182
188
/// ```
183
189
///
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:
186
192
///
187
193
/// ```compile_fail,E0277
188
194
/// for i in ..5 {
189
195
/// // ...
190
196
/// }
191
197
/// ```
192
198
///
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
194
200
/// elements before the index indicated by `end`.
195
201
///
196
202
/// ```
@@ -200,6 +206,10 @@ impl<Idx: PartialOrd<Idx>> RangeFrom<Idx> {
200
206
/// assert_eq!(arr[1.. ], [ 1,2,3]);
201
207
/// assert_eq!(arr[1..3], [ 1,2 ]);
202
208
/// ```
209
+ ///
210
+ /// [`IntoIterator`]: ../iter/trait.Iterator.html
211
+ /// [`Iterator`]: ../iter/trait.IntoIterator.html
212
+ /// [slicing index]: ../slice/trait.SliceIndex.html
203
213
#[ derive( Copy , Clone , PartialEq , Eq , Hash ) ]
204
214
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
205
215
pub struct RangeTo < Idx > {
@@ -217,38 +227,42 @@ impl<Idx: fmt::Debug> fmt::Debug for RangeTo<Idx> {
217
227
218
228
#[ unstable( feature = "range_contains" , reason = "recently added as per RFC" , issue = "32311" ) ]
219
229
impl < Idx : PartialOrd < Idx > > RangeTo < Idx > {
230
+ /// Returns `true` if `item` is contained in the range.
231
+ ///
220
232
/// # Examples
221
233
///
222
234
/// ```
223
235
/// #![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
+ /// # }
229
242
/// ```
230
243
pub fn contains ( & self , item : Idx ) -> bool {
231
244
( item < self . end )
232
245
}
233
246
}
234
247
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`).
237
249
///
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`.
239
252
///
240
253
/// # Examples
241
254
///
242
255
/// ```
243
256
/// #![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());
247
257
///
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
+ /// # }
252
266
/// ```
253
267
#[ derive( Clone , PartialEq , Eq , Hash ) ] // not Copy -- see #27186
254
268
#[ unstable( feature = "inclusive_range" , reason = "recently added, follows RFC" , issue = "28237" ) ]
@@ -274,43 +288,44 @@ impl<Idx: fmt::Debug> fmt::Debug for RangeInclusive<Idx> {
274
288
275
289
#[ unstable( feature = "range_contains" , reason = "recently added as per RFC" , issue = "32311" ) ]
276
290
impl < Idx : PartialOrd < Idx > > RangeInclusive < Idx > {
291
+ /// Returns `true` if `item` is contained in the range.
292
+ ///
277
293
/// # Examples
278
294
///
279
295
/// ```
280
296
/// #![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));
287
297
///
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
+ /// # }
291
308
/// ```
292
309
pub fn contains ( & self , item : Idx ) -> bool {
293
310
self . start <= item && item <= self . end
294
311
}
295
312
}
296
313
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`).
301
315
///
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.
303
318
///
304
319
/// # Examples
305
320
///
306
- /// The `...{integer} ` syntax is a `RangeToInclusive`:
321
+ /// The `...end ` syntax is a `RangeToInclusive`:
307
322
///
308
323
/// ```
309
324
/// #![feature(inclusive_range,inclusive_range_syntax)]
310
325
/// assert_eq!((...5), std::ops::RangeToInclusive{ end: 5 });
311
326
/// ```
312
327
///
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
314
329
/// `for` loop directly. This won't compile:
315
330
///
316
331
/// ```compile_fail,E0277
@@ -320,15 +335,22 @@ impl<Idx: PartialOrd<Idx>> RangeInclusive<Idx> {
320
335
/// }
321
336
/// ```
322
337
///
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
324
339
/// array elements up to and including the index indicated by `end`.
325
340
///
326
341
/// ```
327
342
/// #![feature(inclusive_range_syntax)]
343
+ ///
344
+ /// # fn main() {
328
345
/// let arr = [0, 1, 2, 3];
329
346
/// assert_eq!(arr[ ...2], [0,1,2 ]); // RangeToInclusive
330
347
/// assert_eq!(arr[1...2], [ 1,2 ]);
348
+ /// # }
331
349
/// ```
350
+ ///
351
+ /// [`IntoIterator`]: ../iter/trait.Iterator.html
352
+ /// [`Iterator`]: ../iter/trait.IntoIterator.html
353
+ /// [slicing index]: ../slice/trait.SliceIndex.html
332
354
#[ derive( Copy , Clone , PartialEq , Eq , Hash ) ]
333
355
#[ unstable( feature = "inclusive_range" , reason = "recently added, follows RFC" , issue = "28237" ) ]
334
356
pub struct RangeToInclusive < Idx > {
@@ -348,15 +370,18 @@ impl<Idx: fmt::Debug> fmt::Debug for RangeToInclusive<Idx> {
348
370
349
371
#[ unstable( feature = "range_contains" , reason = "recently added as per RFC" , issue = "32311" ) ]
350
372
impl < Idx : PartialOrd < Idx > > RangeToInclusive < Idx > {
373
+ /// Returns `true` if `item` is contained in the range.
374
+ ///
351
375
/// # Examples
352
376
///
353
377
/// ```
354
378
/// #![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
+ /// # }
360
385
/// ```
361
386
pub fn contains ( & self , item : Idx ) -> bool {
362
387
( item <= self . end )
0 commit comments