]>
Commit | Line | Data |
---|---|---|
1a4d82fc JJ |
1 | // Copyright 2014 The Rust Project Developers. See the COPYRIGHT |
2 | // file at the top-level directory of this distribution and at | |
3 | // http://rust-lang.org/COPYRIGHT. | |
4 | // | |
5 | // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or | |
6 | // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license | |
7 | // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your | |
8 | // option. This file may not be copied, modified, or distributed | |
9 | // except according to those terms. | |
10 | ||
c34b1796 AL |
11 | //! A growable list type with heap-allocated contents, written `Vec<T>` but |
12 | //! pronounced 'vector.' | |
1a4d82fc JJ |
13 | //! |
14 | //! Vectors have `O(1)` indexing, push (to the end) and pop (from the end). | |
15 | //! | |
16 | //! # Examples | |
17 | //! | |
d9579d0f | 18 | //! You can explicitly create a `Vec<T>` with `new()`: |
1a4d82fc JJ |
19 | //! |
20 | //! ``` | |
d9579d0f | 21 | //! let v: Vec<i32> = Vec::new(); |
1a4d82fc JJ |
22 | //! ``` |
23 | //! | |
d9579d0f | 24 | //! ...or by using the `vec!` macro: |
1a4d82fc JJ |
25 | //! |
26 | //! ``` | |
d9579d0f | 27 | //! let v: Vec<i32> = vec![]; |
1a4d82fc | 28 | //! |
d9579d0f AL |
29 | //! let v = vec![1, 2, 3, 4, 5]; |
30 | //! | |
31 | //! let v = vec![0; 10]; // ten zeroes | |
1a4d82fc JJ |
32 | //! ``` |
33 | //! | |
d9579d0f | 34 | //! You can `push` values onto the end of a vector (which will grow the vector as needed): |
1a4d82fc JJ |
35 | //! |
36 | //! ``` | |
d9579d0f | 37 | //! let mut v = vec![1, 2]; |
1a4d82fc | 38 | //! |
d9579d0f | 39 | //! v.push(3); |
1a4d82fc JJ |
40 | //! ``` |
41 | //! | |
d9579d0f AL |
42 | //! Popping values works in much the same way: |
43 | //! | |
44 | //! ``` | |
45 | //! let mut v = vec![1, 2]; | |
1a4d82fc | 46 | //! |
d9579d0f | 47 | //! let two = v.pop(); |
1a4d82fc | 48 | //! ``` |
1a4d82fc | 49 | //! |
d9579d0f AL |
50 | //! Vectors also support indexing (through the `Index` and `IndexMut` traits): |
51 | //! | |
52 | //! ``` | |
53 | //! let mut v = vec![1, 2, 3]; | |
54 | //! let three = v[2]; | |
55 | //! v[1] = v[1] + 5; | |
1a4d82fc JJ |
56 | //! ``` |
57 | ||
85aaf69f | 58 | #![stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
59 | |
60 | use core::prelude::*; | |
61 | ||
62 | use alloc::boxed::Box; | |
63 | use alloc::heap::{EMPTY, allocate, reallocate, deallocate}; | |
1a4d82fc | 64 | use core::cmp::max; |
c34b1796 | 65 | use core::cmp::Ordering; |
1a4d82fc JJ |
66 | use core::fmt; |
67 | use core::hash::{self, Hash}; | |
85aaf69f | 68 | use core::intrinsics::assume; |
9346a6ac | 69 | use core::iter::{repeat, FromIterator}; |
85aaf69f | 70 | use core::marker::PhantomData; |
1a4d82fc | 71 | use core::mem; |
bd371182 | 72 | use core::ops::{Index, IndexMut, Deref}; |
1a4d82fc JJ |
73 | use core::ops; |
74 | use core::ptr; | |
85aaf69f | 75 | use core::ptr::Unique; |
85aaf69f | 76 | use core::slice; |
9346a6ac | 77 | use core::isize; |
85aaf69f SL |
78 | use core::usize; |
79 | ||
80 | use borrow::{Cow, IntoCow}; | |
1a4d82fc | 81 | |
d9579d0f AL |
82 | use super::range::RangeArgument; |
83 | ||
9346a6ac AL |
84 | // FIXME- fix places which assume the max vector allowed has memory usize::MAX. |
85 | static MAX_MEMORY_SIZE: usize = isize::MAX as usize; | |
86 | ||
1a4d82fc JJ |
87 | /// A growable list type, written `Vec<T>` but pronounced 'vector.' |
88 | /// | |
89 | /// # Examples | |
90 | /// | |
91 | /// ``` | |
c34b1796 | 92 | /// # #![feature(collections)] |
1a4d82fc | 93 | /// let mut vec = Vec::new(); |
85aaf69f SL |
94 | /// vec.push(1); |
95 | /// vec.push(2); | |
1a4d82fc JJ |
96 | /// |
97 | /// assert_eq!(vec.len(), 2); | |
98 | /// assert_eq!(vec[0], 1); | |
99 | /// | |
100 | /// assert_eq!(vec.pop(), Some(2)); | |
101 | /// assert_eq!(vec.len(), 1); | |
102 | /// | |
85aaf69f | 103 | /// vec[0] = 7; |
1a4d82fc JJ |
104 | /// assert_eq!(vec[0], 7); |
105 | /// | |
106 | /// vec.push_all(&[1, 2, 3]); | |
107 | /// | |
108 | /// for x in vec.iter() { | |
109 | /// println!("{}", x); | |
110 | /// } | |
c34b1796 | 111 | /// assert_eq!(vec, [7, 1, 2, 3]); |
1a4d82fc JJ |
112 | /// ``` |
113 | /// | |
114 | /// The `vec!` macro is provided to make initialization more convenient: | |
115 | /// | |
116 | /// ``` | |
85aaf69f | 117 | /// let mut vec = vec![1, 2, 3]; |
1a4d82fc | 118 | /// vec.push(4); |
c34b1796 | 119 | /// assert_eq!(vec, [1, 2, 3, 4]); |
1a4d82fc JJ |
120 | /// ``` |
121 | /// | |
122 | /// Use a `Vec<T>` as an efficient stack: | |
123 | /// | |
124 | /// ``` | |
125 | /// let mut stack = Vec::new(); | |
126 | /// | |
85aaf69f SL |
127 | /// stack.push(1); |
128 | /// stack.push(2); | |
129 | /// stack.push(3); | |
1a4d82fc | 130 | /// |
bd371182 | 131 | /// while let Some(top) = stack.pop() { |
1a4d82fc JJ |
132 | /// // Prints 3, 2, 1 |
133 | /// println!("{}", top); | |
134 | /// } | |
135 | /// ``` | |
136 | /// | |
137 | /// # Capacity and reallocation | |
138 | /// | |
c34b1796 AL |
139 | /// The capacity of a vector is the amount of space allocated for any future |
140 | /// elements that will be added onto the vector. This is not to be confused with | |
141 | /// the *length* of a vector, which specifies the number of actual elements | |
142 | /// within the vector. If a vector's length exceeds its capacity, its capacity | |
143 | /// will automatically be increased, but its elements will have to be | |
1a4d82fc JJ |
144 | /// reallocated. |
145 | /// | |
c34b1796 AL |
146 | /// For example, a vector with capacity 10 and length 0 would be an empty vector |
147 | /// with space for 10 more elements. Pushing 10 or fewer elements onto the | |
148 | /// vector will not change its capacity or cause reallocation to occur. However, | |
149 | /// if the vector's length is increased to 11, it will have to reallocate, which | |
150 | /// can be slow. For this reason, it is recommended to use `Vec::with_capacity` | |
151 | /// whenever possible to specify how big the vector is expected to get. | |
1a4d82fc | 152 | #[unsafe_no_drop_flag] |
85aaf69f | 153 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 154 | pub struct Vec<T> { |
85aaf69f SL |
155 | ptr: Unique<T>, |
156 | len: usize, | |
157 | cap: usize, | |
1a4d82fc JJ |
158 | } |
159 | ||
160 | unsafe impl<T: Send> Send for Vec<T> { } | |
161 | unsafe impl<T: Sync> Sync for Vec<T> { } | |
162 | ||
163 | //////////////////////////////////////////////////////////////////////////////// | |
164 | // Inherent methods | |
165 | //////////////////////////////////////////////////////////////////////////////// | |
166 | ||
167 | impl<T> Vec<T> { | |
168 | /// Constructs a new, empty `Vec<T>`. | |
169 | /// | |
170 | /// The vector will not allocate until elements are pushed onto it. | |
171 | /// | |
172 | /// # Examples | |
173 | /// | |
174 | /// ``` | |
85aaf69f | 175 | /// let mut vec: Vec<i32> = Vec::new(); |
1a4d82fc JJ |
176 | /// ``` |
177 | #[inline] | |
85aaf69f | 178 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
179 | pub fn new() -> Vec<T> { |
180 | // We want ptr to never be NULL so instead we set it to some arbitrary | |
181 | // non-null value which is fine since we never call deallocate on the ptr | |
182 | // if cap is 0. The reason for this is because the pointer of a slice | |
183 | // being NULL would break the null pointer optimization for enums. | |
85aaf69f | 184 | unsafe { Vec::from_raw_parts(EMPTY as *mut T, 0, 0) } |
1a4d82fc JJ |
185 | } |
186 | ||
187 | /// Constructs a new, empty `Vec<T>` with the specified capacity. | |
188 | /// | |
189 | /// The vector will be able to hold exactly `capacity` elements without reallocating. If | |
190 | /// `capacity` is 0, the vector will not allocate. | |
191 | /// | |
192 | /// It is important to note that this function does not specify the *length* of the returned | |
193 | /// vector, but only the *capacity*. (For an explanation of the difference between length and | |
194 | /// capacity, see the main `Vec<T>` docs above, 'Capacity and reallocation'.) | |
195 | /// | |
196 | /// # Examples | |
197 | /// | |
198 | /// ``` | |
9346a6ac | 199 | /// let mut vec = Vec::with_capacity(10); |
1a4d82fc JJ |
200 | /// |
201 | /// // The vector contains no items, even though it has capacity for more | |
202 | /// assert_eq!(vec.len(), 0); | |
203 | /// | |
204 | /// // These are all done without reallocating... | |
85aaf69f | 205 | /// for i in 0..10 { |
1a4d82fc JJ |
206 | /// vec.push(i); |
207 | /// } | |
208 | /// | |
209 | /// // ...but this may make the vector reallocate | |
210 | /// vec.push(11); | |
211 | /// ``` | |
212 | #[inline] | |
85aaf69f SL |
213 | #[stable(feature = "rust1", since = "1.0.0")] |
214 | pub fn with_capacity(capacity: usize) -> Vec<T> { | |
1a4d82fc | 215 | if mem::size_of::<T>() == 0 { |
85aaf69f | 216 | unsafe { Vec::from_raw_parts(EMPTY as *mut T, 0, usize::MAX) } |
1a4d82fc JJ |
217 | } else if capacity == 0 { |
218 | Vec::new() | |
219 | } else { | |
220 | let size = capacity.checked_mul(mem::size_of::<T>()) | |
221 | .expect("capacity overflow"); | |
222 | let ptr = unsafe { allocate(size, mem::min_align_of::<T>()) }; | |
223 | if ptr.is_null() { ::alloc::oom() } | |
85aaf69f | 224 | unsafe { Vec::from_raw_parts(ptr as *mut T, 0, capacity) } |
1a4d82fc JJ |
225 | } |
226 | } | |
227 | ||
228 | /// Creates a `Vec<T>` directly from the raw components of another vector. | |
229 | /// | |
230 | /// This is highly unsafe, due to the number of invariants that aren't checked. | |
231 | /// | |
232 | /// # Examples | |
233 | /// | |
234 | /// ``` | |
235 | /// use std::ptr; | |
236 | /// use std::mem; | |
237 | /// | |
238 | /// fn main() { | |
85aaf69f | 239 | /// let mut v = vec![1, 2, 3]; |
1a4d82fc JJ |
240 | /// |
241 | /// // Pull out the various important pieces of information about `v` | |
242 | /// let p = v.as_mut_ptr(); | |
243 | /// let len = v.len(); | |
244 | /// let cap = v.capacity(); | |
245 | /// | |
246 | /// unsafe { | |
247 | /// // Cast `v` into the void: no destructor run, so we are in | |
248 | /// // complete control of the allocation to which `p` points. | |
249 | /// mem::forget(v); | |
250 | /// | |
251 | /// // Overwrite memory with 4, 5, 6 | |
85aaf69f | 252 | /// for i in 0..len as isize { |
1a4d82fc JJ |
253 | /// ptr::write(p.offset(i), 4 + i); |
254 | /// } | |
255 | /// | |
256 | /// // Put everything back together into a Vec | |
257 | /// let rebuilt = Vec::from_raw_parts(p, len, cap); | |
c34b1796 | 258 | /// assert_eq!(rebuilt, [4, 5, 6]); |
1a4d82fc JJ |
259 | /// } |
260 | /// } | |
261 | /// ``` | |
85aaf69f SL |
262 | #[stable(feature = "rust1", since = "1.0.0")] |
263 | pub unsafe fn from_raw_parts(ptr: *mut T, length: usize, | |
264 | capacity: usize) -> Vec<T> { | |
265 | Vec { | |
266 | ptr: Unique::new(ptr), | |
267 | len: length, | |
268 | cap: capacity, | |
269 | } | |
1a4d82fc JJ |
270 | } |
271 | ||
272 | /// Creates a vector by copying the elements from a raw pointer. | |
273 | /// | |
c34b1796 AL |
274 | /// This function will copy `elts` contiguous elements starting at `ptr` |
275 | /// into a new allocation owned by the returned `Vec<T>`. The elements of | |
276 | /// the buffer are copied into the vector without cloning, as if | |
277 | /// `ptr::read()` were called on them. | |
1a4d82fc | 278 | #[inline] |
85aaf69f SL |
279 | #[unstable(feature = "collections", |
280 | reason = "may be better expressed via composition")] | |
281 | pub unsafe fn from_raw_buf(ptr: *const T, elts: usize) -> Vec<T> { | |
1a4d82fc JJ |
282 | let mut dst = Vec::with_capacity(elts); |
283 | dst.set_len(elts); | |
c34b1796 | 284 | ptr::copy_nonoverlapping(ptr, dst.as_mut_ptr(), elts); |
1a4d82fc JJ |
285 | dst |
286 | } | |
287 | ||
288 | /// Returns the number of elements the vector can hold without | |
289 | /// reallocating. | |
290 | /// | |
291 | /// # Examples | |
292 | /// | |
293 | /// ``` | |
85aaf69f | 294 | /// let vec: Vec<i32> = Vec::with_capacity(10); |
1a4d82fc JJ |
295 | /// assert_eq!(vec.capacity(), 10); |
296 | /// ``` | |
297 | #[inline] | |
85aaf69f SL |
298 | #[stable(feature = "rust1", since = "1.0.0")] |
299 | pub fn capacity(&self) -> usize { | |
1a4d82fc JJ |
300 | self.cap |
301 | } | |
302 | ||
c34b1796 AL |
303 | /// Reserves capacity for at least `additional` more elements to be inserted |
304 | /// in the given `Vec<T>`. The collection may reserve more space to avoid | |
305 | /// frequent reallocations. | |
1a4d82fc JJ |
306 | /// |
307 | /// # Panics | |
308 | /// | |
85aaf69f | 309 | /// Panics if the new capacity overflows `usize`. |
1a4d82fc JJ |
310 | /// |
311 | /// # Examples | |
312 | /// | |
313 | /// ``` | |
85aaf69f | 314 | /// let mut vec = vec![1]; |
1a4d82fc JJ |
315 | /// vec.reserve(10); |
316 | /// assert!(vec.capacity() >= 11); | |
317 | /// ``` | |
85aaf69f SL |
318 | #[stable(feature = "rust1", since = "1.0.0")] |
319 | pub fn reserve(&mut self, additional: usize) { | |
1a4d82fc | 320 | if self.cap - self.len < additional { |
9346a6ac AL |
321 | const ERR_MSG: &'static str = "Vec::reserve: `isize` overflow"; |
322 | ||
323 | let new_min_cap = self.len.checked_add(additional).expect(ERR_MSG); | |
324 | if new_min_cap > MAX_MEMORY_SIZE { panic!(ERR_MSG) } | |
325 | self.grow_capacity(match new_min_cap.checked_next_power_of_two() { | |
326 | Some(x) if x > MAX_MEMORY_SIZE => MAX_MEMORY_SIZE, | |
327 | None => MAX_MEMORY_SIZE, | |
328 | Some(x) => x, | |
329 | }); | |
1a4d82fc JJ |
330 | } |
331 | } | |
332 | ||
333 | /// Reserves the minimum capacity for exactly `additional` more elements to | |
334 | /// be inserted in the given `Vec<T>`. Does nothing if the capacity is already | |
335 | /// sufficient. | |
336 | /// | |
337 | /// Note that the allocator may give the collection more space than it | |
338 | /// requests. Therefore capacity can not be relied upon to be precisely | |
339 | /// minimal. Prefer `reserve` if future insertions are expected. | |
340 | /// | |
341 | /// # Panics | |
342 | /// | |
85aaf69f | 343 | /// Panics if the new capacity overflows `usize`. |
1a4d82fc JJ |
344 | /// |
345 | /// # Examples | |
346 | /// | |
347 | /// ``` | |
85aaf69f | 348 | /// let mut vec = vec![1]; |
1a4d82fc JJ |
349 | /// vec.reserve_exact(10); |
350 | /// assert!(vec.capacity() >= 11); | |
351 | /// ``` | |
85aaf69f SL |
352 | #[stable(feature = "rust1", since = "1.0.0")] |
353 | pub fn reserve_exact(&mut self, additional: usize) { | |
1a4d82fc JJ |
354 | if self.cap - self.len < additional { |
355 | match self.len.checked_add(additional) { | |
85aaf69f | 356 | None => panic!("Vec::reserve: `usize` overflow"), |
1a4d82fc JJ |
357 | Some(new_cap) => self.grow_capacity(new_cap) |
358 | } | |
359 | } | |
360 | } | |
361 | ||
362 | /// Shrinks the capacity of the vector as much as possible. | |
363 | /// | |
364 | /// It will drop down as close as possible to the length but the allocator | |
365 | /// may still inform the vector that there is space for a few more elements. | |
366 | /// | |
367 | /// # Examples | |
368 | /// | |
369 | /// ``` | |
c34b1796 | 370 | /// # #![feature(collections)] |
85aaf69f | 371 | /// let mut vec = Vec::with_capacity(10); |
1a4d82fc JJ |
372 | /// vec.push_all(&[1, 2, 3]); |
373 | /// assert_eq!(vec.capacity(), 10); | |
374 | /// vec.shrink_to_fit(); | |
375 | /// assert!(vec.capacity() >= 3); | |
376 | /// ``` | |
85aaf69f | 377 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
378 | pub fn shrink_to_fit(&mut self) { |
379 | if mem::size_of::<T>() == 0 { return } | |
380 | ||
381 | if self.len == 0 { | |
382 | if self.cap != 0 { | |
383 | unsafe { | |
384 | dealloc(*self.ptr, self.cap) | |
385 | } | |
386 | self.cap = 0; | |
387 | } | |
85aaf69f | 388 | } else if self.cap != self.len { |
1a4d82fc JJ |
389 | unsafe { |
390 | // Overflow check is unnecessary as the vector is already at | |
391 | // least this large. | |
392 | let ptr = reallocate(*self.ptr as *mut u8, | |
393 | self.cap * mem::size_of::<T>(), | |
394 | self.len * mem::size_of::<T>(), | |
395 | mem::min_align_of::<T>()) as *mut T; | |
396 | if ptr.is_null() { ::alloc::oom() } | |
85aaf69f | 397 | self.ptr = Unique::new(ptr); |
1a4d82fc JJ |
398 | } |
399 | self.cap = self.len; | |
400 | } | |
401 | } | |
402 | ||
9346a6ac | 403 | /// Converts the vector into Box<[T]>. |
1a4d82fc JJ |
404 | /// |
405 | /// Note that this will drop any excess capacity. Calling this and | |
406 | /// converting back to a vector with `into_vec()` is equivalent to calling | |
407 | /// `shrink_to_fit()`. | |
c34b1796 | 408 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
409 | pub fn into_boxed_slice(mut self) -> Box<[T]> { |
410 | self.shrink_to_fit(); | |
411 | unsafe { | |
c34b1796 | 412 | let xs: Box<[T]> = Box::from_raw(&mut *self); |
1a4d82fc JJ |
413 | mem::forget(self); |
414 | xs | |
415 | } | |
416 | } | |
417 | ||
418 | /// Shorten a vector, dropping excess elements. | |
419 | /// | |
420 | /// If `len` is greater than the vector's current length, this has no | |
421 | /// effect. | |
422 | /// | |
423 | /// # Examples | |
424 | /// | |
425 | /// ``` | |
c34b1796 | 426 | /// # #![feature(collections)] |
85aaf69f | 427 | /// let mut vec = vec![1, 2, 3, 4]; |
1a4d82fc | 428 | /// vec.truncate(2); |
c34b1796 | 429 | /// assert_eq!(vec, [1, 2]); |
1a4d82fc | 430 | /// ``` |
85aaf69f SL |
431 | #[stable(feature = "rust1", since = "1.0.0")] |
432 | pub fn truncate(&mut self, len: usize) { | |
1a4d82fc JJ |
433 | unsafe { |
434 | // drop any extra elements | |
435 | while len < self.len { | |
436 | // decrement len before the read(), so a panic on Drop doesn't | |
437 | // re-drop the just-failed value. | |
438 | self.len -= 1; | |
439 | ptr::read(self.get_unchecked(self.len)); | |
440 | } | |
441 | } | |
442 | } | |
443 | ||
9346a6ac | 444 | /// Extracts a slice containing the entire vector. |
1a4d82fc | 445 | #[inline] |
c34b1796 AL |
446 | #[unstable(feature = "convert", |
447 | reason = "waiting on RFC revision")] | |
448 | pub fn as_slice(&self) -> &[T] { | |
449 | self | |
450 | } | |
451 | ||
452 | /// Deprecated: use `&mut s[..]` instead. | |
453 | #[inline] | |
454 | #[unstable(feature = "convert", | |
455 | reason = "waiting on RFC revision")] | |
85aaf69f | 456 | pub fn as_mut_slice(&mut self) -> &mut [T] { |
c34b1796 | 457 | &mut self[..] |
1a4d82fc JJ |
458 | } |
459 | ||
1a4d82fc JJ |
460 | /// Sets the length of a vector. |
461 | /// | |
462 | /// This will explicitly set the size of the vector, without actually | |
463 | /// modifying its buffers, so it is up to the caller to ensure that the | |
464 | /// vector is actually the specified size. | |
465 | /// | |
466 | /// # Examples | |
467 | /// | |
468 | /// ``` | |
85aaf69f | 469 | /// let mut v = vec![1, 2, 3, 4]; |
1a4d82fc JJ |
470 | /// unsafe { |
471 | /// v.set_len(1); | |
472 | /// } | |
473 | /// ``` | |
474 | #[inline] | |
85aaf69f SL |
475 | #[stable(feature = "rust1", since = "1.0.0")] |
476 | pub unsafe fn set_len(&mut self, len: usize) { | |
1a4d82fc JJ |
477 | self.len = len; |
478 | } | |
479 | ||
480 | /// Removes an element from anywhere in the vector and return it, replacing | |
481 | /// it with the last element. | |
482 | /// | |
483 | /// This does not preserve ordering, but is O(1). | |
484 | /// | |
485 | /// # Panics | |
486 | /// | |
487 | /// Panics if `index` is out of bounds. | |
488 | /// | |
489 | /// # Examples | |
490 | /// | |
491 | /// ``` | |
492 | /// let mut v = vec!["foo", "bar", "baz", "qux"]; | |
493 | /// | |
494 | /// assert_eq!(v.swap_remove(1), "bar"); | |
c34b1796 | 495 | /// assert_eq!(v, ["foo", "qux", "baz"]); |
1a4d82fc JJ |
496 | /// |
497 | /// assert_eq!(v.swap_remove(0), "foo"); | |
c34b1796 | 498 | /// assert_eq!(v, ["baz", "qux"]); |
1a4d82fc JJ |
499 | /// ``` |
500 | #[inline] | |
85aaf69f SL |
501 | #[stable(feature = "rust1", since = "1.0.0")] |
502 | pub fn swap_remove(&mut self, index: usize) -> T { | |
1a4d82fc JJ |
503 | let length = self.len(); |
504 | self.swap(index, length - 1); | |
505 | self.pop().unwrap() | |
506 | } | |
507 | ||
508 | /// Inserts an element at position `index` within the vector, shifting all | |
509 | /// elements after position `i` one position to the right. | |
510 | /// | |
511 | /// # Panics | |
512 | /// | |
9346a6ac | 513 | /// Panics if `index` is greater than the vector's length. |
1a4d82fc JJ |
514 | /// |
515 | /// # Examples | |
516 | /// | |
517 | /// ``` | |
85aaf69f | 518 | /// let mut vec = vec![1, 2, 3]; |
1a4d82fc | 519 | /// vec.insert(1, 4); |
c34b1796 | 520 | /// assert_eq!(vec, [1, 4, 2, 3]); |
1a4d82fc | 521 | /// vec.insert(4, 5); |
c34b1796 | 522 | /// assert_eq!(vec, [1, 4, 2, 3, 5]); |
1a4d82fc | 523 | /// ``` |
85aaf69f SL |
524 | #[stable(feature = "rust1", since = "1.0.0")] |
525 | pub fn insert(&mut self, index: usize, element: T) { | |
1a4d82fc JJ |
526 | let len = self.len(); |
527 | assert!(index <= len); | |
528 | // space for the new element | |
529 | self.reserve(1); | |
530 | ||
531 | unsafe { // infallible | |
532 | // The spot to put the new value | |
533 | { | |
85aaf69f | 534 | let p = self.as_mut_ptr().offset(index as isize); |
1a4d82fc JJ |
535 | // Shift everything over to make space. (Duplicating the |
536 | // `index`th element into two consecutive places.) | |
c34b1796 | 537 | ptr::copy(&*p, p.offset(1), len - index); |
1a4d82fc JJ |
538 | // Write it in, overwriting the first copy of the `index`th |
539 | // element. | |
540 | ptr::write(&mut *p, element); | |
541 | } | |
542 | self.set_len(len + 1); | |
543 | } | |
544 | } | |
545 | ||
546 | /// Removes and returns the element at position `index` within the vector, | |
547 | /// shifting all elements after position `index` one position to the left. | |
548 | /// | |
549 | /// # Panics | |
550 | /// | |
bd371182 | 551 | /// Panics if `index` is out of bounds. |
1a4d82fc JJ |
552 | /// |
553 | /// # Examples | |
554 | /// | |
555 | /// ``` | |
c34b1796 | 556 | /// # #![feature(collections)] |
85aaf69f | 557 | /// let mut v = vec![1, 2, 3]; |
1a4d82fc | 558 | /// assert_eq!(v.remove(1), 2); |
c34b1796 | 559 | /// assert_eq!(v, [1, 3]); |
1a4d82fc | 560 | /// ``` |
85aaf69f SL |
561 | #[stable(feature = "rust1", since = "1.0.0")] |
562 | pub fn remove(&mut self, index: usize) -> T { | |
1a4d82fc JJ |
563 | let len = self.len(); |
564 | assert!(index < len); | |
565 | unsafe { // infallible | |
566 | let ret; | |
567 | { | |
568 | // the place we are taking from. | |
85aaf69f | 569 | let ptr = self.as_mut_ptr().offset(index as isize); |
1a4d82fc JJ |
570 | // copy it out, unsafely having a copy of the value on |
571 | // the stack and in the vector at the same time. | |
85aaf69f | 572 | ret = ptr::read(ptr); |
1a4d82fc JJ |
573 | |
574 | // Shift everything down to fill in that spot. | |
c34b1796 | 575 | ptr::copy(&*ptr.offset(1), ptr, len - index - 1); |
1a4d82fc JJ |
576 | } |
577 | self.set_len(len - 1); | |
578 | ret | |
579 | } | |
580 | } | |
581 | ||
582 | /// Retains only the elements specified by the predicate. | |
583 | /// | |
584 | /// In other words, remove all elements `e` such that `f(&e)` returns false. | |
585 | /// This method operates in place and preserves the order of the retained | |
586 | /// elements. | |
587 | /// | |
588 | /// # Examples | |
589 | /// | |
590 | /// ``` | |
85aaf69f | 591 | /// let mut vec = vec![1, 2, 3, 4]; |
1a4d82fc | 592 | /// vec.retain(|&x| x%2 == 0); |
c34b1796 | 593 | /// assert_eq!(vec, [2, 4]); |
1a4d82fc | 594 | /// ``` |
85aaf69f | 595 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
596 | pub fn retain<F>(&mut self, mut f: F) where F: FnMut(&T) -> bool { |
597 | let len = self.len(); | |
85aaf69f | 598 | let mut del = 0; |
1a4d82fc | 599 | { |
85aaf69f | 600 | let v = &mut **self; |
1a4d82fc | 601 | |
85aaf69f | 602 | for i in 0..len { |
1a4d82fc JJ |
603 | if !f(&v[i]) { |
604 | del += 1; | |
605 | } else if del > 0 { | |
606 | v.swap(i-del, i); | |
607 | } | |
608 | } | |
609 | } | |
610 | if del > 0 { | |
611 | self.truncate(len - del); | |
612 | } | |
613 | } | |
614 | ||
615 | /// Appends an element to the back of a collection. | |
616 | /// | |
617 | /// # Panics | |
618 | /// | |
85aaf69f | 619 | /// Panics if the number of elements in the vector overflows a `usize`. |
1a4d82fc JJ |
620 | /// |
621 | /// # Examples | |
622 | /// | |
c34b1796 | 623 | /// ``` |
85aaf69f | 624 | /// let mut vec = vec!(1, 2); |
1a4d82fc | 625 | /// vec.push(3); |
c34b1796 | 626 | /// assert_eq!(vec, [1, 2, 3]); |
1a4d82fc JJ |
627 | /// ``` |
628 | #[inline] | |
85aaf69f | 629 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 630 | pub fn push(&mut self, value: T) { |
c34b1796 AL |
631 | #[cold] |
632 | #[inline(never)] | |
633 | fn resize<T>(vec: &mut Vec<T>) { | |
634 | let old_size = vec.cap * mem::size_of::<T>(); | |
9346a6ac AL |
635 | if old_size >= MAX_MEMORY_SIZE { panic!("capacity overflow") } |
636 | let mut size = max(old_size, 2 * mem::size_of::<T>()) * 2; | |
637 | if old_size > size || size > MAX_MEMORY_SIZE { | |
638 | size = MAX_MEMORY_SIZE; | |
639 | } | |
c34b1796 AL |
640 | unsafe { |
641 | let ptr = alloc_or_realloc(*vec.ptr, old_size, size); | |
642 | if ptr.is_null() { ::alloc::oom() } | |
643 | vec.ptr = Unique::new(ptr); | |
644 | } | |
645 | vec.cap = max(vec.cap, 2) * 2; | |
646 | } | |
647 | ||
1a4d82fc JJ |
648 | if mem::size_of::<T>() == 0 { |
649 | // zero-size types consume no memory, so we can't rely on the | |
650 | // address space running out | |
651 | self.len = self.len.checked_add(1).expect("length overflow"); | |
bd371182 | 652 | mem::forget(value); |
1a4d82fc JJ |
653 | return |
654 | } | |
c34b1796 | 655 | |
1a4d82fc | 656 | if self.len == self.cap { |
c34b1796 | 657 | resize(self); |
1a4d82fc JJ |
658 | } |
659 | ||
660 | unsafe { | |
85aaf69f | 661 | let end = (*self.ptr).offset(self.len as isize); |
1a4d82fc JJ |
662 | ptr::write(&mut *end, value); |
663 | self.len += 1; | |
664 | } | |
665 | } | |
666 | ||
667 | /// Removes the last element from a vector and returns it, or `None` if it is empty. | |
668 | /// | |
669 | /// # Examples | |
670 | /// | |
c34b1796 | 671 | /// ``` |
85aaf69f | 672 | /// let mut vec = vec![1, 2, 3]; |
1a4d82fc | 673 | /// assert_eq!(vec.pop(), Some(3)); |
c34b1796 | 674 | /// assert_eq!(vec, [1, 2]); |
1a4d82fc JJ |
675 | /// ``` |
676 | #[inline] | |
85aaf69f | 677 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
678 | pub fn pop(&mut self) -> Option<T> { |
679 | if self.len == 0 { | |
680 | None | |
681 | } else { | |
682 | unsafe { | |
683 | self.len -= 1; | |
684 | Some(ptr::read(self.get_unchecked(self.len()))) | |
685 | } | |
686 | } | |
687 | } | |
688 | ||
85aaf69f SL |
689 | /// Moves all the elements of `other` into `Self`, leaving `other` empty. |
690 | /// | |
691 | /// # Panics | |
692 | /// | |
693 | /// Panics if the number of elements in the vector overflows a `usize`. | |
694 | /// | |
695 | /// # Examples | |
696 | /// | |
697 | /// ``` | |
c34b1796 | 698 | /// # #![feature(collections)] |
85aaf69f SL |
699 | /// let mut vec = vec![1, 2, 3]; |
700 | /// let mut vec2 = vec![4, 5, 6]; | |
701 | /// vec.append(&mut vec2); | |
c34b1796 AL |
702 | /// assert_eq!(vec, [1, 2, 3, 4, 5, 6]); |
703 | /// assert_eq!(vec2, []); | |
85aaf69f SL |
704 | /// ``` |
705 | #[inline] | |
706 | #[unstable(feature = "collections", | |
707 | reason = "new API, waiting for dust to settle")] | |
708 | pub fn append(&mut self, other: &mut Self) { | |
709 | if mem::size_of::<T>() == 0 { | |
710 | // zero-size types consume no memory, so we can't rely on the | |
711 | // address space running out | |
712 | self.len = self.len.checked_add(other.len()).expect("length overflow"); | |
713 | unsafe { other.set_len(0) } | |
714 | return; | |
715 | } | |
716 | self.reserve(other.len()); | |
717 | let len = self.len(); | |
718 | unsafe { | |
c34b1796 | 719 | ptr::copy_nonoverlapping( |
85aaf69f | 720 | other.as_ptr(), |
c34b1796 | 721 | self.get_unchecked_mut(len), |
85aaf69f SL |
722 | other.len()); |
723 | } | |
724 | ||
725 | self.len += other.len(); | |
726 | unsafe { other.set_len(0); } | |
727 | } | |
728 | ||
d9579d0f AL |
729 | /// Create a draining iterator that removes the specified range in the vector |
730 | /// and yields the removed items from start to end. The element range is | |
731 | /// removed even if the iterator is not consumed until the end. | |
732 | /// | |
733 | /// Note: It is unspecified how many elements are removed from the vector, | |
734 | /// if the `Drain` value is leaked. | |
735 | /// | |
736 | /// # Panics | |
737 | /// | |
738 | /// Panics if the starting point is greater than the end point or if | |
739 | /// the end point is greater than the length of the vector. | |
1a4d82fc JJ |
740 | /// |
741 | /// # Examples | |
742 | /// | |
743 | /// ``` | |
d9579d0f AL |
744 | /// # #![feature(collections_drain, collections_range)] |
745 | /// | |
746 | /// // Draining using `..` clears the whole vector. | |
747 | /// let mut v = vec![1, 2, 3]; | |
748 | /// let u: Vec<_> = v.drain(..).collect(); | |
749 | /// assert_eq!(v, &[]); | |
750 | /// assert_eq!(u, &[1, 2, 3]); | |
1a4d82fc | 751 | /// ``` |
d9579d0f AL |
752 | #[unstable(feature = "collections_drain", |
753 | reason = "recently added, matches RFC")] | |
754 | pub fn drain<R>(&mut self, range: R) -> Drain<T> where R: RangeArgument<usize> { | |
755 | // Memory safety | |
756 | // | |
757 | // When the Drain is first created, it shortens the length of | |
758 | // the source vector to make sure no uninitalized or moved-from elements | |
759 | // are accessible at all if the Drain's destructor never gets to run. | |
760 | // | |
761 | // Drain will ptr::read out the values to remove. | |
762 | // When finished, remaining tail of the vec is copied back to cover | |
763 | // the hole, and the vector length is restored to the new length. | |
764 | // | |
765 | let len = self.len(); | |
766 | let start = *range.start().unwrap_or(&0); | |
767 | let end = *range.end().unwrap_or(&len); | |
768 | assert!(start <= end); | |
769 | assert!(end <= len); | |
770 | ||
1a4d82fc | 771 | unsafe { |
d9579d0f AL |
772 | // set self.vec length's to start, to be safe in case Drain is leaked |
773 | self.set_len(start); | |
774 | // Use the borrow in the IterMut to indicate borrowing behavior of the | |
775 | // whole Drain iterator (like &mut T). | |
776 | let range_slice = slice::from_raw_parts_mut( | |
777 | self.as_mut_ptr().offset(start as isize), | |
778 | end - start); | |
1a4d82fc | 779 | Drain { |
d9579d0f AL |
780 | tail_start: end, |
781 | tail_len: len - end, | |
782 | iter: range_slice.iter_mut(), | |
783 | vec: self as *mut _, | |
1a4d82fc JJ |
784 | } |
785 | } | |
786 | } | |
787 | ||
788 | /// Clears the vector, removing all values. | |
789 | /// | |
790 | /// # Examples | |
791 | /// | |
792 | /// ``` | |
85aaf69f | 793 | /// let mut v = vec![1, 2, 3]; |
1a4d82fc JJ |
794 | /// |
795 | /// v.clear(); | |
796 | /// | |
797 | /// assert!(v.is_empty()); | |
798 | /// ``` | |
799 | #[inline] | |
85aaf69f | 800 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
801 | pub fn clear(&mut self) { |
802 | self.truncate(0) | |
803 | } | |
804 | ||
805 | /// Returns the number of elements in the vector. | |
806 | /// | |
807 | /// # Examples | |
808 | /// | |
809 | /// ``` | |
85aaf69f | 810 | /// let a = vec![1, 2, 3]; |
1a4d82fc JJ |
811 | /// assert_eq!(a.len(), 3); |
812 | /// ``` | |
813 | #[inline] | |
85aaf69f SL |
814 | #[stable(feature = "rust1", since = "1.0.0")] |
815 | pub fn len(&self) -> usize { self.len } | |
1a4d82fc JJ |
816 | |
817 | /// Returns `true` if the vector contains no elements. | |
818 | /// | |
819 | /// # Examples | |
820 | /// | |
821 | /// ``` | |
822 | /// let mut v = Vec::new(); | |
823 | /// assert!(v.is_empty()); | |
824 | /// | |
85aaf69f | 825 | /// v.push(1); |
1a4d82fc JJ |
826 | /// assert!(!v.is_empty()); |
827 | /// ``` | |
85aaf69f | 828 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
829 | pub fn is_empty(&self) -> bool { self.len() == 0 } |
830 | ||
831 | /// Converts a `Vec<T>` to a `Vec<U>` where `T` and `U` have the same | |
832 | /// size and in case they are not zero-sized the same minimal alignment. | |
833 | /// | |
834 | /// # Panics | |
835 | /// | |
836 | /// Panics if `T` and `U` have differing sizes or are not zero-sized and | |
837 | /// have differing minimal alignments. | |
838 | /// | |
839 | /// # Examples | |
840 | /// | |
841 | /// ``` | |
c34b1796 | 842 | /// # #![feature(collections, core)] |
85aaf69f | 843 | /// let v = vec![0, 1, 2]; |
1a4d82fc | 844 | /// let w = v.map_in_place(|i| i + 3); |
c34b1796 | 845 | /// assert_eq!(&w[..], &[3, 4, 5]); |
1a4d82fc | 846 | /// |
85aaf69f | 847 | /// #[derive(PartialEq, Debug)] |
1a4d82fc JJ |
848 | /// struct Newtype(u8); |
849 | /// let bytes = vec![0x11, 0x22]; | |
850 | /// let newtyped_bytes = bytes.map_in_place(|x| Newtype(x)); | |
c34b1796 | 851 | /// assert_eq!(&newtyped_bytes[..], &[Newtype(0x11), Newtype(0x22)]); |
1a4d82fc | 852 | /// ``` |
85aaf69f SL |
853 | #[unstable(feature = "collections", |
854 | reason = "API may change to provide stronger guarantees")] | |
1a4d82fc JJ |
855 | pub fn map_in_place<U, F>(self, mut f: F) -> Vec<U> where F: FnMut(T) -> U { |
856 | // FIXME: Assert statically that the types `T` and `U` have the same | |
857 | // size. | |
858 | assert!(mem::size_of::<T>() == mem::size_of::<U>()); | |
859 | ||
860 | let mut vec = self; | |
861 | ||
862 | if mem::size_of::<T>() != 0 { | |
863 | // FIXME: Assert statically that the types `T` and `U` have the | |
864 | // same minimal alignment in case they are not zero-sized. | |
865 | ||
866 | // These asserts are necessary because the `min_align_of` of the | |
867 | // types are passed to the allocator by `Vec`. | |
868 | assert!(mem::min_align_of::<T>() == mem::min_align_of::<U>()); | |
869 | ||
85aaf69f | 870 | // This `as isize` cast is safe, because the size of the elements of the |
1a4d82fc JJ |
871 | // vector is not 0, and: |
872 | // | |
85aaf69f | 873 | // 1) If the size of the elements in the vector is 1, the `isize` may |
1a4d82fc JJ |
874 | // overflow, but it has the correct bit pattern so that the |
875 | // `.offset()` function will work. | |
876 | // | |
877 | // Example: | |
878 | // Address space 0x0-0xF. | |
879 | // `u8` array at: 0x1. | |
880 | // Size of `u8` array: 0x8. | |
881 | // Calculated `offset`: -0x8. | |
882 | // After `array.offset(offset)`: 0x9. | |
883 | // (0x1 + 0x8 = 0x1 - 0x8) | |
884 | // | |
85aaf69f SL |
885 | // 2) If the size of the elements in the vector is >1, the `usize` -> |
886 | // `isize` conversion can't overflow. | |
887 | let offset = vec.len() as isize; | |
1a4d82fc JJ |
888 | let start = vec.as_mut_ptr(); |
889 | ||
890 | let mut pv = PartialVecNonZeroSized { | |
891 | vec: vec, | |
892 | ||
893 | start_t: start, | |
894 | // This points inside the vector, as the vector has length | |
895 | // `offset`. | |
896 | end_t: unsafe { start.offset(offset) }, | |
897 | start_u: start as *mut U, | |
898 | end_u: start as *mut U, | |
85aaf69f SL |
899 | |
900 | _marker: PhantomData, | |
1a4d82fc JJ |
901 | }; |
902 | // start_t | |
903 | // start_u | |
904 | // | | |
905 | // +-+-+-+-+-+-+ | |
906 | // |T|T|T|...|T| | |
907 | // +-+-+-+-+-+-+ | |
908 | // | | | |
909 | // end_u end_t | |
910 | ||
911 | while pv.end_u as *mut T != pv.end_t { | |
912 | unsafe { | |
913 | // start_u start_t | |
914 | // | | | |
915 | // +-+-+-+-+-+-+-+-+-+ | |
916 | // |U|...|U|T|T|...|T| | |
917 | // +-+-+-+-+-+-+-+-+-+ | |
918 | // | | | |
919 | // end_u end_t | |
920 | ||
85aaf69f | 921 | let t = ptr::read(pv.start_t); |
1a4d82fc JJ |
922 | // start_u start_t |
923 | // | | | |
924 | // +-+-+-+-+-+-+-+-+-+ | |
925 | // |U|...|U|X|T|...|T| | |
926 | // +-+-+-+-+-+-+-+-+-+ | |
927 | // | | | |
928 | // end_u end_t | |
929 | // We must not panic here, one cell is marked as `T` | |
930 | // although it is not `T`. | |
931 | ||
932 | pv.start_t = pv.start_t.offset(1); | |
933 | // start_u start_t | |
934 | // | | | |
935 | // +-+-+-+-+-+-+-+-+-+ | |
936 | // |U|...|U|X|T|...|T| | |
937 | // +-+-+-+-+-+-+-+-+-+ | |
938 | // | | | |
939 | // end_u end_t | |
940 | // We may panic again. | |
941 | ||
942 | // The function given by the user might panic. | |
943 | let u = f(t); | |
944 | ||
945 | ptr::write(pv.end_u, u); | |
946 | // start_u start_t | |
947 | // | | | |
948 | // +-+-+-+-+-+-+-+-+-+ | |
949 | // |U|...|U|U|T|...|T| | |
950 | // +-+-+-+-+-+-+-+-+-+ | |
951 | // | | | |
952 | // end_u end_t | |
953 | // We should not panic here, because that would leak the `U` | |
954 | // pointed to by `end_u`. | |
955 | ||
956 | pv.end_u = pv.end_u.offset(1); | |
957 | // start_u start_t | |
958 | // | | | |
959 | // +-+-+-+-+-+-+-+-+-+ | |
960 | // |U|...|U|U|T|...|T| | |
961 | // +-+-+-+-+-+-+-+-+-+ | |
962 | // | | | |
963 | // end_u end_t | |
964 | // We may panic again. | |
965 | } | |
966 | } | |
967 | ||
968 | // start_u start_t | |
969 | // | | | |
970 | // +-+-+-+-+-+-+ | |
971 | // |U|...|U|U|U| | |
972 | // +-+-+-+-+-+-+ | |
973 | // | | |
974 | // end_t | |
975 | // end_u | |
976 | // Extract `vec` and prevent the destructor of | |
977 | // `PartialVecNonZeroSized` from running. Note that none of the | |
978 | // function calls can panic, thus no resources can be leaked (as the | |
979 | // `vec` member of `PartialVec` is the only one which holds | |
980 | // allocations -- and it is returned from this function. None of | |
981 | // this can panic. | |
982 | unsafe { | |
983 | let vec_len = pv.vec.len(); | |
984 | let vec_cap = pv.vec.capacity(); | |
985 | let vec_ptr = pv.vec.as_mut_ptr() as *mut U; | |
986 | mem::forget(pv); | |
987 | Vec::from_raw_parts(vec_ptr, vec_len, vec_cap) | |
988 | } | |
989 | } else { | |
990 | // Put the `Vec` into the `PartialVecZeroSized` structure and | |
991 | // prevent the destructor of the `Vec` from running. Since the | |
992 | // `Vec` contained zero-sized objects, it did not allocate, so we | |
993 | // are not leaking memory here. | |
994 | let mut pv = PartialVecZeroSized::<T,U> { | |
995 | num_t: vec.len(), | |
996 | num_u: 0, | |
85aaf69f | 997 | marker: PhantomData, |
1a4d82fc | 998 | }; |
bd371182 | 999 | mem::forget(vec); |
1a4d82fc JJ |
1000 | |
1001 | while pv.num_t != 0 { | |
1002 | unsafe { | |
1003 | // Create a `T` out of thin air and decrement `num_t`. This | |
1004 | // must not panic between these steps, as otherwise a | |
1005 | // destructor of `T` which doesn't exist runs. | |
1006 | let t = mem::uninitialized(); | |
1007 | pv.num_t -= 1; | |
1008 | ||
1009 | // The function given by the user might panic. | |
1010 | let u = f(t); | |
1011 | ||
1012 | // Forget the `U` and increment `num_u`. This increment | |
85aaf69f SL |
1013 | // cannot overflow the `usize` as we only do this for a |
1014 | // number of times that fits into a `usize` (and start with | |
1a4d82fc JJ |
1015 | // `0`). Again, we should not panic between these steps. |
1016 | mem::forget(u); | |
1017 | pv.num_u += 1; | |
1018 | } | |
1019 | } | |
1020 | // Create a `Vec` from our `PartialVecZeroSized` and make sure the | |
1021 | // destructor of the latter will not run. None of this can panic. | |
1022 | let mut result = Vec::new(); | |
1023 | unsafe { | |
1024 | result.set_len(pv.num_u); | |
1025 | mem::forget(pv); | |
1026 | } | |
1027 | result | |
1028 | } | |
1029 | } | |
85aaf69f SL |
1030 | |
1031 | /// Splits the collection into two at the given index. | |
1032 | /// | |
1033 | /// Returns a newly allocated `Self`. `self` contains elements `[0, at)`, | |
1034 | /// and the returned `Self` contains elements `[at, len)`. | |
1035 | /// | |
1036 | /// Note that the capacity of `self` does not change. | |
1037 | /// | |
1038 | /// # Panics | |
1039 | /// | |
1040 | /// Panics if `at > len`. | |
1041 | /// | |
1042 | /// # Examples | |
1043 | /// | |
1044 | /// ``` | |
c34b1796 | 1045 | /// # #![feature(collections)] |
85aaf69f SL |
1046 | /// let mut vec = vec![1,2,3]; |
1047 | /// let vec2 = vec.split_off(1); | |
c34b1796 AL |
1048 | /// assert_eq!(vec, [1]); |
1049 | /// assert_eq!(vec2, [2, 3]); | |
85aaf69f SL |
1050 | /// ``` |
1051 | #[inline] | |
1052 | #[unstable(feature = "collections", | |
1053 | reason = "new API, waiting for dust to settle")] | |
1054 | pub fn split_off(&mut self, at: usize) -> Self { | |
1055 | assert!(at <= self.len(), "`at` out of bounds"); | |
1056 | ||
1057 | let other_len = self.len - at; | |
1058 | let mut other = Vec::with_capacity(other_len); | |
1059 | ||
1060 | // Unsafely `set_len` and copy items to `other`. | |
1061 | unsafe { | |
1062 | self.set_len(at); | |
1063 | other.set_len(other_len); | |
1064 | ||
c34b1796 | 1065 | ptr::copy_nonoverlapping( |
85aaf69f | 1066 | self.as_ptr().offset(at as isize), |
c34b1796 | 1067 | other.as_mut_ptr(), |
85aaf69f SL |
1068 | other.len()); |
1069 | } | |
1070 | other | |
1071 | } | |
1072 | ||
1a4d82fc JJ |
1073 | } |
1074 | ||
1075 | impl<T: Clone> Vec<T> { | |
1076 | /// Resizes the `Vec` in-place so that `len()` is equal to `new_len`. | |
1077 | /// | |
1078 | /// Calls either `extend()` or `truncate()` depending on whether `new_len` | |
1079 | /// is larger than the current value of `len()` or not. | |
1080 | /// | |
1081 | /// # Examples | |
1082 | /// | |
1083 | /// ``` | |
c34b1796 | 1084 | /// # #![feature(collections)] |
1a4d82fc JJ |
1085 | /// let mut vec = vec!["hello"]; |
1086 | /// vec.resize(3, "world"); | |
c34b1796 | 1087 | /// assert_eq!(vec, ["hello", "world", "world"]); |
1a4d82fc | 1088 | /// |
85aaf69f | 1089 | /// let mut vec = vec![1, 2, 3, 4]; |
1a4d82fc | 1090 | /// vec.resize(2, 0); |
c34b1796 | 1091 | /// assert_eq!(vec, [1, 2]); |
1a4d82fc | 1092 | /// ``` |
85aaf69f SL |
1093 | #[unstable(feature = "collections", |
1094 | reason = "matches collection reform specification; waiting for dust to settle")] | |
1095 | pub fn resize(&mut self, new_len: usize, value: T) { | |
1a4d82fc JJ |
1096 | let len = self.len(); |
1097 | ||
1098 | if new_len > len { | |
1099 | self.extend(repeat(value).take(new_len - len)); | |
1100 | } else { | |
1101 | self.truncate(new_len); | |
1102 | } | |
1103 | } | |
1104 | ||
1105 | /// Appends all elements in a slice to the `Vec`. | |
1106 | /// | |
1107 | /// Iterates over the slice `other`, clones each element, and then appends | |
1108 | /// it to this `Vec`. The `other` vector is traversed in-order. | |
1109 | /// | |
1110 | /// # Examples | |
1111 | /// | |
1112 | /// ``` | |
c34b1796 | 1113 | /// # #![feature(collections)] |
85aaf69f SL |
1114 | /// let mut vec = vec![1]; |
1115 | /// vec.push_all(&[2, 3, 4]); | |
c34b1796 | 1116 | /// assert_eq!(vec, [1, 2, 3, 4]); |
1a4d82fc JJ |
1117 | /// ``` |
1118 | #[inline] | |
85aaf69f SL |
1119 | #[unstable(feature = "collections", |
1120 | reason = "likely to be replaced by a more optimized extend")] | |
1a4d82fc JJ |
1121 | pub fn push_all(&mut self, other: &[T]) { |
1122 | self.reserve(other.len()); | |
1123 | ||
85aaf69f | 1124 | for i in 0..other.len() { |
1a4d82fc JJ |
1125 | let len = self.len(); |
1126 | ||
1127 | // Unsafe code so this can be optimised to a memcpy (or something similarly | |
1128 | // fast) when T is Copy. LLVM is easily confused, so any extra operations | |
1129 | // during the loop can prevent this optimisation. | |
1130 | unsafe { | |
1131 | ptr::write( | |
1132 | self.get_unchecked_mut(len), | |
1133 | other.get_unchecked(i).clone()); | |
1134 | self.set_len(len + 1); | |
1135 | } | |
1136 | } | |
1137 | } | |
1138 | } | |
1139 | ||
1140 | impl<T: PartialEq> Vec<T> { | |
1141 | /// Removes consecutive repeated elements in the vector. | |
1142 | /// | |
1143 | /// If the vector is sorted, this removes all duplicates. | |
1144 | /// | |
1145 | /// # Examples | |
1146 | /// | |
1147 | /// ``` | |
85aaf69f | 1148 | /// let mut vec = vec![1, 2, 2, 3, 2]; |
1a4d82fc JJ |
1149 | /// |
1150 | /// vec.dedup(); | |
1151 | /// | |
c34b1796 | 1152 | /// assert_eq!(vec, [1, 2, 3, 2]); |
1a4d82fc | 1153 | /// ``` |
85aaf69f | 1154 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
1155 | pub fn dedup(&mut self) { |
1156 | unsafe { | |
1157 | // Although we have a mutable reference to `self`, we cannot make | |
1158 | // *arbitrary* changes. The `PartialEq` comparisons could panic, so we | |
1159 | // must ensure that the vector is in a valid state at all time. | |
1160 | // | |
1161 | // The way that we handle this is by using swaps; we iterate | |
1162 | // over all the elements, swapping as we go so that at the end | |
1163 | // the elements we wish to keep are in the front, and those we | |
1164 | // wish to reject are at the back. We can then truncate the | |
1165 | // vector. This operation is still O(n). | |
1166 | // | |
1167 | // Example: We start in this state, where `r` represents "next | |
1168 | // read" and `w` represents "next_write`. | |
1169 | // | |
1170 | // r | |
1171 | // +---+---+---+---+---+---+ | |
1172 | // | 0 | 1 | 1 | 2 | 3 | 3 | | |
1173 | // +---+---+---+---+---+---+ | |
1174 | // w | |
1175 | // | |
1176 | // Comparing self[r] against self[w-1], this is not a duplicate, so | |
1177 | // we swap self[r] and self[w] (no effect as r==w) and then increment both | |
1178 | // r and w, leaving us with: | |
1179 | // | |
1180 | // r | |
1181 | // +---+---+---+---+---+---+ | |
1182 | // | 0 | 1 | 1 | 2 | 3 | 3 | | |
1183 | // +---+---+---+---+---+---+ | |
1184 | // w | |
1185 | // | |
1186 | // Comparing self[r] against self[w-1], this value is a duplicate, | |
1187 | // so we increment `r` but leave everything else unchanged: | |
1188 | // | |
1189 | // r | |
1190 | // +---+---+---+---+---+---+ | |
1191 | // | 0 | 1 | 1 | 2 | 3 | 3 | | |
1192 | // +---+---+---+---+---+---+ | |
1193 | // w | |
1194 | // | |
1195 | // Comparing self[r] against self[w-1], this is not a duplicate, | |
1196 | // so swap self[r] and self[w] and advance r and w: | |
1197 | // | |
1198 | // r | |
1199 | // +---+---+---+---+---+---+ | |
1200 | // | 0 | 1 | 2 | 1 | 3 | 3 | | |
1201 | // +---+---+---+---+---+---+ | |
1202 | // w | |
1203 | // | |
1204 | // Not a duplicate, repeat: | |
1205 | // | |
1206 | // r | |
1207 | // +---+---+---+---+---+---+ | |
1208 | // | 0 | 1 | 2 | 3 | 1 | 3 | | |
1209 | // +---+---+---+---+---+---+ | |
1210 | // w | |
1211 | // | |
1212 | // Duplicate, advance r. End of vec. Truncate to w. | |
1213 | ||
1214 | let ln = self.len(); | |
1215 | if ln < 1 { return; } | |
1216 | ||
1217 | // Avoid bounds checks by using unsafe pointers. | |
1218 | let p = self.as_mut_ptr(); | |
c34b1796 AL |
1219 | let mut r: usize = 1; |
1220 | let mut w: usize = 1; | |
1a4d82fc JJ |
1221 | |
1222 | while r < ln { | |
85aaf69f SL |
1223 | let p_r = p.offset(r as isize); |
1224 | let p_wm1 = p.offset((w - 1) as isize); | |
1a4d82fc JJ |
1225 | if *p_r != *p_wm1 { |
1226 | if r != w { | |
1227 | let p_w = p_wm1.offset(1); | |
1228 | mem::swap(&mut *p_r, &mut *p_w); | |
1229 | } | |
1230 | w += 1; | |
1231 | } | |
1232 | r += 1; | |
1233 | } | |
1234 | ||
1235 | self.truncate(w); | |
1236 | } | |
1237 | } | |
1238 | } | |
1239 | ||
1240 | //////////////////////////////////////////////////////////////////////////////// | |
1241 | // Internal methods and functions | |
1242 | //////////////////////////////////////////////////////////////////////////////// | |
1243 | ||
1244 | impl<T> Vec<T> { | |
1245 | /// Reserves capacity for exactly `capacity` elements in the given vector. | |
1246 | /// | |
1247 | /// If the capacity for `self` is already equal to or greater than the | |
1248 | /// requested capacity, then no action is taken. | |
85aaf69f | 1249 | fn grow_capacity(&mut self, capacity: usize) { |
1a4d82fc JJ |
1250 | if mem::size_of::<T>() == 0 { return } |
1251 | ||
1252 | if capacity > self.cap { | |
1253 | let size = capacity.checked_mul(mem::size_of::<T>()) | |
1254 | .expect("capacity overflow"); | |
1255 | unsafe { | |
1256 | let ptr = alloc_or_realloc(*self.ptr, self.cap * mem::size_of::<T>(), size); | |
1257 | if ptr.is_null() { ::alloc::oom() } | |
85aaf69f | 1258 | self.ptr = Unique::new(ptr); |
1a4d82fc JJ |
1259 | } |
1260 | self.cap = capacity; | |
1261 | } | |
1262 | } | |
1263 | } | |
1264 | ||
1265 | // FIXME: #13996: need a way to mark the return value as `noalias` | |
1266 | #[inline(never)] | |
85aaf69f | 1267 | unsafe fn alloc_or_realloc<T>(ptr: *mut T, old_size: usize, size: usize) -> *mut T { |
1a4d82fc JJ |
1268 | if old_size == 0 { |
1269 | allocate(size, mem::min_align_of::<T>()) as *mut T | |
1270 | } else { | |
1271 | reallocate(ptr as *mut u8, old_size, size, mem::min_align_of::<T>()) as *mut T | |
1272 | } | |
1273 | } | |
1274 | ||
1275 | #[inline] | |
85aaf69f | 1276 | unsafe fn dealloc<T>(ptr: *mut T, len: usize) { |
1a4d82fc JJ |
1277 | if mem::size_of::<T>() != 0 { |
1278 | deallocate(ptr as *mut u8, | |
1279 | len * mem::size_of::<T>(), | |
1280 | mem::min_align_of::<T>()) | |
1281 | } | |
1282 | } | |
1283 | ||
85aaf69f SL |
1284 | #[doc(hidden)] |
1285 | #[stable(feature = "rust1", since = "1.0.0")] | |
1286 | pub fn from_elem<T: Clone>(elem: T, n: usize) -> Vec<T> { | |
1287 | unsafe { | |
1288 | let mut v = Vec::with_capacity(n); | |
1289 | let mut ptr = v.as_mut_ptr(); | |
1290 | ||
1291 | // Write all elements except the last one | |
1292 | for i in 1..n { | |
1293 | ptr::write(ptr, Clone::clone(&elem)); | |
1294 | ptr = ptr.offset(1); | |
1295 | v.set_len(i); // Increment the length in every step in case Clone::clone() panics | |
1296 | } | |
1297 | ||
1298 | if n > 0 { | |
1299 | // We can write the last element directly without cloning needlessly | |
1300 | ptr::write(ptr, elem); | |
1301 | v.set_len(n); | |
1302 | } | |
1303 | ||
1304 | v | |
1305 | } | |
1306 | } | |
1307 | ||
1a4d82fc JJ |
1308 | //////////////////////////////////////////////////////////////////////////////// |
1309 | // Common trait implementations for Vec | |
1310 | //////////////////////////////////////////////////////////////////////////////// | |
1311 | ||
bd371182 | 1312 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 1313 | impl<T:Clone> Clone for Vec<T> { |
c34b1796 AL |
1314 | #[cfg(not(test))] |
1315 | fn clone(&self) -> Vec<T> { <[T]>::to_vec(&**self) } | |
1316 | ||
1317 | // HACK(japaric): with cfg(test) the inherent `[T]::to_vec` method, which is | |
1318 | // required for this method definition, is not available. Instead use the | |
1319 | // `slice::to_vec` function which is only available with cfg(test) | |
1320 | // NB see the slice::hack module in slice.rs for more information | |
1321 | #[cfg(test)] | |
1322 | fn clone(&self) -> Vec<T> { | |
1323 | ::slice::to_vec(&**self) | |
1324 | } | |
1a4d82fc JJ |
1325 | |
1326 | fn clone_from(&mut self, other: &Vec<T>) { | |
1327 | // drop anything in self that will not be overwritten | |
1328 | if self.len() > other.len() { | |
1329 | self.truncate(other.len()) | |
1330 | } | |
1331 | ||
1332 | // reuse the contained values' allocations/resources. | |
1333 | for (place, thing) in self.iter_mut().zip(other.iter()) { | |
1334 | place.clone_from(thing) | |
1335 | } | |
1336 | ||
1337 | // self.len <= other.len due to the truncate above, so the | |
1338 | // slice here is always in-bounds. | |
1339 | let slice = &other[self.len()..]; | |
1340 | self.push_all(slice); | |
1341 | } | |
1342 | } | |
1343 | ||
85aaf69f | 1344 | #[stable(feature = "rust1", since = "1.0.0")] |
85aaf69f | 1345 | impl<T: Hash> Hash for Vec<T> { |
1a4d82fc | 1346 | #[inline] |
85aaf69f SL |
1347 | fn hash<H: hash::Hasher>(&self, state: &mut H) { |
1348 | Hash::hash(&**self, state) | |
1a4d82fc JJ |
1349 | } |
1350 | } | |
1351 | ||
85aaf69f SL |
1352 | #[stable(feature = "rust1", since = "1.0.0")] |
1353 | impl<T> Index<usize> for Vec<T> { | |
1a4d82fc JJ |
1354 | type Output = T; |
1355 | ||
1356 | #[inline] | |
c34b1796 | 1357 | fn index(&self, index: usize) -> &T { |
85aaf69f | 1358 | // NB built-in indexing via `&[T]` |
c34b1796 | 1359 | &(**self)[index] |
1a4d82fc JJ |
1360 | } |
1361 | } | |
1362 | ||
85aaf69f SL |
1363 | #[stable(feature = "rust1", since = "1.0.0")] |
1364 | impl<T> IndexMut<usize> for Vec<T> { | |
1a4d82fc | 1365 | #[inline] |
c34b1796 | 1366 | fn index_mut(&mut self, index: usize) -> &mut T { |
85aaf69f | 1367 | // NB built-in indexing via `&mut [T]` |
c34b1796 | 1368 | &mut (**self)[index] |
1a4d82fc JJ |
1369 | } |
1370 | } | |
1371 | ||
1372 | ||
85aaf69f SL |
1373 | #[stable(feature = "rust1", since = "1.0.0")] |
1374 | impl<T> ops::Index<ops::Range<usize>> for Vec<T> { | |
1a4d82fc | 1375 | type Output = [T]; |
c34b1796 | 1376 | |
1a4d82fc | 1377 | #[inline] |
c34b1796 | 1378 | fn index(&self, index: ops::Range<usize>) -> &[T] { |
85aaf69f | 1379 | Index::index(&**self, index) |
1a4d82fc JJ |
1380 | } |
1381 | } | |
85aaf69f SL |
1382 | #[stable(feature = "rust1", since = "1.0.0")] |
1383 | impl<T> ops::Index<ops::RangeTo<usize>> for Vec<T> { | |
1a4d82fc | 1384 | type Output = [T]; |
c34b1796 | 1385 | |
1a4d82fc | 1386 | #[inline] |
c34b1796 | 1387 | fn index(&self, index: ops::RangeTo<usize>) -> &[T] { |
85aaf69f | 1388 | Index::index(&**self, index) |
1a4d82fc JJ |
1389 | } |
1390 | } | |
85aaf69f SL |
1391 | #[stable(feature = "rust1", since = "1.0.0")] |
1392 | impl<T> ops::Index<ops::RangeFrom<usize>> for Vec<T> { | |
1a4d82fc | 1393 | type Output = [T]; |
c34b1796 | 1394 | |
1a4d82fc | 1395 | #[inline] |
c34b1796 | 1396 | fn index(&self, index: ops::RangeFrom<usize>) -> &[T] { |
85aaf69f | 1397 | Index::index(&**self, index) |
1a4d82fc JJ |
1398 | } |
1399 | } | |
85aaf69f SL |
1400 | #[stable(feature = "rust1", since = "1.0.0")] |
1401 | impl<T> ops::Index<ops::RangeFull> for Vec<T> { | |
1a4d82fc | 1402 | type Output = [T]; |
c34b1796 | 1403 | |
1a4d82fc | 1404 | #[inline] |
c34b1796 AL |
1405 | fn index(&self, _index: ops::RangeFull) -> &[T] { |
1406 | self | |
1a4d82fc JJ |
1407 | } |
1408 | } | |
1409 | ||
85aaf69f SL |
1410 | #[stable(feature = "rust1", since = "1.0.0")] |
1411 | impl<T> ops::IndexMut<ops::Range<usize>> for Vec<T> { | |
c34b1796 | 1412 | |
1a4d82fc | 1413 | #[inline] |
c34b1796 | 1414 | fn index_mut(&mut self, index: ops::Range<usize>) -> &mut [T] { |
85aaf69f | 1415 | IndexMut::index_mut(&mut **self, index) |
1a4d82fc JJ |
1416 | } |
1417 | } | |
85aaf69f SL |
1418 | #[stable(feature = "rust1", since = "1.0.0")] |
1419 | impl<T> ops::IndexMut<ops::RangeTo<usize>> for Vec<T> { | |
c34b1796 | 1420 | |
1a4d82fc | 1421 | #[inline] |
c34b1796 | 1422 | fn index_mut(&mut self, index: ops::RangeTo<usize>) -> &mut [T] { |
85aaf69f | 1423 | IndexMut::index_mut(&mut **self, index) |
1a4d82fc JJ |
1424 | } |
1425 | } | |
85aaf69f SL |
1426 | #[stable(feature = "rust1", since = "1.0.0")] |
1427 | impl<T> ops::IndexMut<ops::RangeFrom<usize>> for Vec<T> { | |
c34b1796 | 1428 | |
1a4d82fc | 1429 | #[inline] |
c34b1796 | 1430 | fn index_mut(&mut self, index: ops::RangeFrom<usize>) -> &mut [T] { |
85aaf69f | 1431 | IndexMut::index_mut(&mut **self, index) |
1a4d82fc JJ |
1432 | } |
1433 | } | |
85aaf69f SL |
1434 | #[stable(feature = "rust1", since = "1.0.0")] |
1435 | impl<T> ops::IndexMut<ops::RangeFull> for Vec<T> { | |
c34b1796 | 1436 | |
1a4d82fc | 1437 | #[inline] |
c34b1796 AL |
1438 | fn index_mut(&mut self, _index: ops::RangeFull) -> &mut [T] { |
1439 | self | |
1a4d82fc JJ |
1440 | } |
1441 | } | |
1442 | ||
85aaf69f | 1443 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
1444 | impl<T> ops::Deref for Vec<T> { |
1445 | type Target = [T]; | |
1446 | ||
c34b1796 AL |
1447 | fn deref(&self) -> &[T] { |
1448 | unsafe { | |
1449 | let p = *self.ptr; | |
1450 | assume(p != 0 as *mut T); | |
1451 | slice::from_raw_parts(p, self.len) | |
1452 | } | |
1453 | } | |
1a4d82fc JJ |
1454 | } |
1455 | ||
85aaf69f | 1456 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 1457 | impl<T> ops::DerefMut for Vec<T> { |
c34b1796 AL |
1458 | fn deref_mut(&mut self) -> &mut [T] { |
1459 | unsafe { | |
1460 | let ptr = *self.ptr; | |
1461 | assume(!ptr.is_null()); | |
1462 | slice::from_raw_parts_mut(ptr, self.len) | |
1463 | } | |
1464 | } | |
1a4d82fc JJ |
1465 | } |
1466 | ||
85aaf69f | 1467 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
1468 | impl<T> FromIterator<T> for Vec<T> { |
1469 | #[inline] | |
85aaf69f SL |
1470 | fn from_iter<I: IntoIterator<Item=T>>(iterable: I) -> Vec<T> { |
1471 | let mut iterator = iterable.into_iter(); | |
1a4d82fc JJ |
1472 | let (lower, _) = iterator.size_hint(); |
1473 | let mut vector = Vec::with_capacity(lower); | |
85aaf69f SL |
1474 | |
1475 | // This function should be the moral equivalent of: | |
1476 | // | |
1477 | // for item in iterator { | |
1478 | // vector.push(item); | |
1479 | // } | |
1480 | // | |
1481 | // This equivalent crucially runs the iterator precisely once. Below we | |
1482 | // actually in theory run the iterator twice (one without bounds checks | |
1483 | // and one with). To achieve the "moral equivalent", we use the `if` | |
1484 | // statement below to break out early. | |
1485 | // | |
1486 | // If the first loop has terminated, then we have one of two conditions. | |
1487 | // | |
1488 | // 1. The underlying iterator returned `None`. In this case we are | |
1489 | // guaranteed that less than `vector.capacity()` elements have been | |
1490 | // returned, so we break out early. | |
1491 | // 2. The underlying iterator yielded `vector.capacity()` elements and | |
1492 | // has not yielded `None` yet. In this case we run the iterator to | |
1493 | // its end below. | |
1494 | for element in iterator.by_ref().take(vector.capacity()) { | |
1495 | let len = vector.len(); | |
1496 | unsafe { | |
1497 | ptr::write(vector.get_unchecked_mut(len), element); | |
1498 | vector.set_len(len + 1); | |
1499 | } | |
1500 | } | |
1501 | ||
1502 | if vector.len() == vector.capacity() { | |
1503 | for element in iterator { | |
1504 | vector.push(element); | |
1505 | } | |
1a4d82fc JJ |
1506 | } |
1507 | vector | |
1508 | } | |
1509 | } | |
1510 | ||
85aaf69f SL |
1511 | #[stable(feature = "rust1", since = "1.0.0")] |
1512 | impl<T> IntoIterator for Vec<T> { | |
1513 | type Item = T; | |
1514 | type IntoIter = IntoIter<T>; | |
1515 | ||
9346a6ac AL |
1516 | /// Creates a consuming iterator, that is, one that moves each value out of |
1517 | /// the vector (from start to end). The vector cannot be used after calling | |
1518 | /// this. | |
1519 | /// | |
1520 | /// # Examples | |
1521 | /// | |
1522 | /// ``` | |
1523 | /// let v = vec!["a".to_string(), "b".to_string()]; | |
1524 | /// for s in v.into_iter() { | |
1525 | /// // s has type String, not &String | |
1526 | /// println!("{}", s); | |
1527 | /// } | |
1528 | /// ``` | |
1529 | #[inline] | |
85aaf69f | 1530 | fn into_iter(self) -> IntoIter<T> { |
9346a6ac AL |
1531 | unsafe { |
1532 | let ptr = *self.ptr; | |
1533 | assume(!ptr.is_null()); | |
1534 | let cap = self.cap; | |
1535 | let begin = ptr as *const T; | |
1536 | let end = if mem::size_of::<T>() == 0 { | |
1537 | (ptr as usize + self.len()) as *const T | |
1538 | } else { | |
1539 | ptr.offset(self.len() as isize) as *const T | |
1540 | }; | |
1541 | mem::forget(self); | |
1542 | IntoIter { allocation: ptr, cap: cap, ptr: begin, end: end } | |
1543 | } | |
85aaf69f SL |
1544 | } |
1545 | } | |
1546 | ||
1547 | #[stable(feature = "rust1", since = "1.0.0")] | |
1548 | impl<'a, T> IntoIterator for &'a Vec<T> { | |
1549 | type Item = &'a T; | |
1550 | type IntoIter = slice::Iter<'a, T>; | |
1551 | ||
1552 | fn into_iter(self) -> slice::Iter<'a, T> { | |
1553 | self.iter() | |
1554 | } | |
1555 | } | |
1556 | ||
1557 | #[stable(feature = "rust1", since = "1.0.0")] | |
1558 | impl<'a, T> IntoIterator for &'a mut Vec<T> { | |
1559 | type Item = &'a mut T; | |
1560 | type IntoIter = slice::IterMut<'a, T>; | |
1561 | ||
1562 | fn into_iter(mut self) -> slice::IterMut<'a, T> { | |
1563 | self.iter_mut() | |
1564 | } | |
1565 | } | |
1566 | ||
bd371182 | 1567 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
1568 | impl<T> Extend<T> for Vec<T> { |
1569 | #[inline] | |
85aaf69f SL |
1570 | fn extend<I: IntoIterator<Item=T>>(&mut self, iterable: I) { |
1571 | let iterator = iterable.into_iter(); | |
1a4d82fc JJ |
1572 | let (lower, _) = iterator.size_hint(); |
1573 | self.reserve(lower); | |
1574 | for element in iterator { | |
1575 | self.push(element) | |
1576 | } | |
1577 | } | |
1578 | } | |
1579 | ||
c34b1796 AL |
1580 | __impl_slice_eq1! { Vec<A>, Vec<B> } |
1581 | __impl_slice_eq1! { Vec<A>, &'b [B] } | |
1582 | __impl_slice_eq1! { Vec<A>, &'b mut [B] } | |
1583 | __impl_slice_eq1! { Cow<'a, [A]>, &'b [B], Clone } | |
1584 | __impl_slice_eq1! { Cow<'a, [A]>, &'b mut [B], Clone } | |
1585 | __impl_slice_eq1! { Cow<'a, [A]>, Vec<B>, Clone } | |
1586 | ||
1587 | macro_rules! array_impls { | |
1588 | ($($N: expr)+) => { | |
1589 | $( | |
1590 | // NOTE: some less important impls are omitted to reduce code bloat | |
1591 | __impl_slice_eq1! { Vec<A>, [B; $N] } | |
1592 | __impl_slice_eq1! { Vec<A>, &'b [B; $N] } | |
1593 | // __impl_slice_eq1! { Vec<A>, &'b mut [B; $N] } | |
1594 | // __impl_slice_eq1! { Cow<'a, [A]>, [B; $N], Clone } | |
1595 | // __impl_slice_eq1! { Cow<'a, [A]>, &'b [B; $N], Clone } | |
1596 | // __impl_slice_eq1! { Cow<'a, [A]>, &'b mut [B; $N], Clone } | |
1597 | )+ | |
1a4d82fc JJ |
1598 | } |
1599 | } | |
1600 | ||
c34b1796 AL |
1601 | array_impls! { |
1602 | 0 1 2 3 4 5 6 7 8 9 | |
1603 | 10 11 12 13 14 15 16 17 18 19 | |
1604 | 20 21 22 23 24 25 26 27 28 29 | |
1605 | 30 31 32 | |
1a4d82fc JJ |
1606 | } |
1607 | ||
85aaf69f | 1608 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
1609 | impl<T: PartialOrd> PartialOrd for Vec<T> { |
1610 | #[inline] | |
1611 | fn partial_cmp(&self, other: &Vec<T>) -> Option<Ordering> { | |
85aaf69f | 1612 | PartialOrd::partial_cmp(&**self, &**other) |
1a4d82fc JJ |
1613 | } |
1614 | } | |
1615 | ||
85aaf69f | 1616 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
1617 | impl<T: Eq> Eq for Vec<T> {} |
1618 | ||
85aaf69f | 1619 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
1620 | impl<T: Ord> Ord for Vec<T> { |
1621 | #[inline] | |
1622 | fn cmp(&self, other: &Vec<T>) -> Ordering { | |
85aaf69f | 1623 | Ord::cmp(&**self, &**other) |
1a4d82fc JJ |
1624 | } |
1625 | } | |
1626 | ||
85aaf69f | 1627 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
1628 | impl<T> Drop for Vec<T> { |
1629 | fn drop(&mut self) { | |
1630 | // This is (and should always remain) a no-op if the fields are | |
1631 | // zeroed (when moving out, because of #[unsafe_no_drop_flag]). | |
c34b1796 | 1632 | if self.cap != 0 && self.cap != mem::POST_DROP_USIZE { |
1a4d82fc | 1633 | unsafe { |
85aaf69f | 1634 | for x in &*self { |
1a4d82fc JJ |
1635 | ptr::read(x); |
1636 | } | |
1637 | dealloc(*self.ptr, self.cap) | |
1638 | } | |
1639 | } | |
1640 | } | |
1641 | } | |
1642 | ||
85aaf69f | 1643 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 1644 | impl<T> Default for Vec<T> { |
85aaf69f | 1645 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
1646 | fn default() -> Vec<T> { |
1647 | Vec::new() | |
1648 | } | |
1649 | } | |
1650 | ||
85aaf69f SL |
1651 | #[stable(feature = "rust1", since = "1.0.0")] |
1652 | impl<T: fmt::Debug> fmt::Debug for Vec<T> { | |
1a4d82fc | 1653 | fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { |
85aaf69f | 1654 | fmt::Debug::fmt(&**self, f) |
1a4d82fc JJ |
1655 | } |
1656 | } | |
1657 | ||
c34b1796 AL |
1658 | #[stable(feature = "rust1", since = "1.0.0")] |
1659 | impl<T> AsRef<Vec<T>> for Vec<T> { | |
1660 | fn as_ref(&self) -> &Vec<T> { | |
1661 | self | |
1662 | } | |
1663 | } | |
1664 | ||
1665 | #[stable(feature = "rust1", since = "1.0.0")] | |
1666 | impl<T> AsRef<[T]> for Vec<T> { | |
1667 | fn as_ref(&self) -> &[T] { | |
1668 | self | |
1669 | } | |
1670 | } | |
1671 | ||
1672 | #[stable(feature = "rust1", since = "1.0.0")] | |
1673 | impl<'a, T: Clone> From<&'a [T]> for Vec<T> { | |
1674 | #[cfg(not(test))] | |
1675 | fn from(s: &'a [T]) -> Vec<T> { | |
1676 | s.to_vec() | |
1677 | } | |
1678 | #[cfg(test)] | |
1679 | fn from(s: &'a [T]) -> Vec<T> { | |
1680 | ::slice::to_vec(s) | |
1681 | } | |
1682 | } | |
1683 | ||
1684 | #[stable(feature = "rust1", since = "1.0.0")] | |
1685 | impl<'a> From<&'a str> for Vec<u8> { | |
1686 | fn from(s: &'a str) -> Vec<u8> { | |
1687 | From::from(s.as_bytes()) | |
1688 | } | |
1689 | } | |
1690 | ||
1a4d82fc JJ |
1691 | //////////////////////////////////////////////////////////////////////////////// |
1692 | // Clone-on-write | |
1693 | //////////////////////////////////////////////////////////////////////////////// | |
1694 | ||
bd371182 | 1695 | #[stable(feature = "rust1", since = "1.0.0")] |
85aaf69f SL |
1696 | impl<'a, T> FromIterator<T> for Cow<'a, [T]> where T: Clone { |
1697 | fn from_iter<I: IntoIterator<Item=T>>(it: I) -> Cow<'a, [T]> { | |
1a4d82fc JJ |
1698 | Cow::Owned(FromIterator::from_iter(it)) |
1699 | } | |
1700 | } | |
1701 | ||
85aaf69f SL |
1702 | impl<'a, T: 'a> IntoCow<'a, [T]> for Vec<T> where T: Clone { |
1703 | fn into_cow(self) -> Cow<'a, [T]> { | |
1a4d82fc JJ |
1704 | Cow::Owned(self) |
1705 | } | |
1706 | } | |
1707 | ||
85aaf69f SL |
1708 | impl<'a, T> IntoCow<'a, [T]> for &'a [T] where T: Clone { |
1709 | fn into_cow(self) -> Cow<'a, [T]> { | |
1a4d82fc JJ |
1710 | Cow::Borrowed(self) |
1711 | } | |
1712 | } | |
1713 | ||
1714 | //////////////////////////////////////////////////////////////////////////////// | |
1715 | // Iterators | |
1716 | //////////////////////////////////////////////////////////////////////////////// | |
1717 | ||
1718 | /// An iterator that moves out of a vector. | |
85aaf69f | 1719 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
1720 | pub struct IntoIter<T> { |
1721 | allocation: *mut T, // the block of memory allocated for the vector | |
85aaf69f | 1722 | cap: usize, // the capacity of the vector |
1a4d82fc JJ |
1723 | ptr: *const T, |
1724 | end: *const T | |
1725 | } | |
1726 | ||
85aaf69f SL |
1727 | unsafe impl<T: Send> Send for IntoIter<T> { } |
1728 | unsafe impl<T: Sync> Sync for IntoIter<T> { } | |
1729 | ||
1a4d82fc JJ |
1730 | impl<T> IntoIter<T> { |
1731 | #[inline] | |
1732 | /// Drops all items that have not yet been moved and returns the empty vector. | |
85aaf69f | 1733 | #[unstable(feature = "collections")] |
1a4d82fc JJ |
1734 | pub fn into_inner(mut self) -> Vec<T> { |
1735 | unsafe { | |
85aaf69f | 1736 | for _x in self.by_ref() { } |
1a4d82fc JJ |
1737 | let IntoIter { allocation, cap, ptr: _ptr, end: _end } = self; |
1738 | mem::forget(self); | |
85aaf69f | 1739 | Vec::from_raw_parts(allocation, 0, cap) |
1a4d82fc JJ |
1740 | } |
1741 | } | |
1742 | } | |
1743 | ||
85aaf69f | 1744 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
1745 | impl<T> Iterator for IntoIter<T> { |
1746 | type Item = T; | |
1747 | ||
1748 | #[inline] | |
85aaf69f | 1749 | fn next(&mut self) -> Option<T> { |
1a4d82fc JJ |
1750 | unsafe { |
1751 | if self.ptr == self.end { | |
1752 | None | |
1753 | } else { | |
1754 | if mem::size_of::<T>() == 0 { | |
1755 | // purposefully don't use 'ptr.offset' because for | |
1756 | // vectors with 0-size elements this would return the | |
1757 | // same pointer. | |
85aaf69f | 1758 | self.ptr = mem::transmute(self.ptr as usize + 1); |
1a4d82fc JJ |
1759 | |
1760 | // Use a non-null pointer value | |
85aaf69f | 1761 | Some(ptr::read(EMPTY as *mut T)) |
1a4d82fc JJ |
1762 | } else { |
1763 | let old = self.ptr; | |
1764 | self.ptr = self.ptr.offset(1); | |
1765 | ||
1766 | Some(ptr::read(old)) | |
1767 | } | |
1768 | } | |
1769 | } | |
1770 | } | |
1771 | ||
1772 | #[inline] | |
85aaf69f SL |
1773 | fn size_hint(&self) -> (usize, Option<usize>) { |
1774 | let diff = (self.end as usize) - (self.ptr as usize); | |
1a4d82fc JJ |
1775 | let size = mem::size_of::<T>(); |
1776 | let exact = diff / (if size == 0 {1} else {size}); | |
1777 | (exact, Some(exact)) | |
1778 | } | |
d9579d0f AL |
1779 | |
1780 | #[inline] | |
1781 | fn count(self) -> usize { | |
1782 | self.size_hint().0 | |
1783 | } | |
1a4d82fc JJ |
1784 | } |
1785 | ||
85aaf69f | 1786 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
1787 | impl<T> DoubleEndedIterator for IntoIter<T> { |
1788 | #[inline] | |
85aaf69f | 1789 | fn next_back(&mut self) -> Option<T> { |
1a4d82fc JJ |
1790 | unsafe { |
1791 | if self.end == self.ptr { | |
1792 | None | |
1793 | } else { | |
1794 | if mem::size_of::<T>() == 0 { | |
1795 | // See above for why 'ptr.offset' isn't used | |
85aaf69f | 1796 | self.end = mem::transmute(self.end as usize - 1); |
1a4d82fc JJ |
1797 | |
1798 | // Use a non-null pointer value | |
85aaf69f | 1799 | Some(ptr::read(EMPTY as *mut T)) |
1a4d82fc JJ |
1800 | } else { |
1801 | self.end = self.end.offset(-1); | |
1802 | ||
1803 | Some(ptr::read(mem::transmute(self.end))) | |
1804 | } | |
1805 | } | |
1806 | } | |
1807 | } | |
1808 | } | |
1809 | ||
85aaf69f | 1810 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
1811 | impl<T> ExactSizeIterator for IntoIter<T> {} |
1812 | ||
85aaf69f | 1813 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
1814 | impl<T> Drop for IntoIter<T> { |
1815 | fn drop(&mut self) { | |
1816 | // destroy the remaining elements | |
1817 | if self.cap != 0 { | |
85aaf69f | 1818 | for _x in self.by_ref() {} |
1a4d82fc JJ |
1819 | unsafe { |
1820 | dealloc(self.allocation, self.cap); | |
1821 | } | |
1822 | } | |
1823 | } | |
1824 | } | |
1825 | ||
d9579d0f AL |
1826 | /// A draining iterator for `Vec<T>`. |
1827 | #[unstable(feature = "collections_drain", reason = "recently added")] | |
1828 | pub struct Drain<'a, T: 'a> { | |
1829 | /// Index of tail to preserve | |
1830 | tail_start: usize, | |
1831 | /// Length of tail | |
1832 | tail_len: usize, | |
1833 | /// Current remaining range to remove | |
1834 | iter: slice::IterMut<'a, T>, | |
1835 | vec: *mut Vec<T>, | |
1a4d82fc JJ |
1836 | } |
1837 | ||
c34b1796 AL |
1838 | unsafe impl<'a, T: Sync> Sync for Drain<'a, T> {} |
1839 | unsafe impl<'a, T: Send> Send for Drain<'a, T> {} | |
1840 | ||
85aaf69f | 1841 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
1842 | impl<'a, T> Iterator for Drain<'a, T> { |
1843 | type Item = T; | |
1844 | ||
1845 | #[inline] | |
1846 | fn next(&mut self) -> Option<T> { | |
d9579d0f AL |
1847 | self.iter.next().map(|elt| |
1848 | unsafe { | |
1849 | ptr::read(elt as *const _) | |
1a4d82fc | 1850 | } |
d9579d0f | 1851 | ) |
1a4d82fc JJ |
1852 | } |
1853 | ||
85aaf69f | 1854 | fn size_hint(&self) -> (usize, Option<usize>) { |
d9579d0f | 1855 | self.iter.size_hint() |
1a4d82fc JJ |
1856 | } |
1857 | } | |
1858 | ||
85aaf69f | 1859 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
1860 | impl<'a, T> DoubleEndedIterator for Drain<'a, T> { |
1861 | #[inline] | |
1862 | fn next_back(&mut self) -> Option<T> { | |
d9579d0f AL |
1863 | self.iter.next_back().map(|elt| |
1864 | unsafe { | |
1865 | ptr::read(elt as *const _) | |
1a4d82fc | 1866 | } |
d9579d0f | 1867 | ) |
1a4d82fc JJ |
1868 | } |
1869 | } | |
1870 | ||
85aaf69f | 1871 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
1872 | impl<'a, T> Drop for Drain<'a, T> { |
1873 | fn drop(&mut self) { | |
d9579d0f AL |
1874 | // exhaust self first |
1875 | while let Some(_) = self.next() { } | |
1a4d82fc | 1876 | |
d9579d0f AL |
1877 | if self.tail_len > 0 { |
1878 | unsafe { | |
1879 | let source_vec = &mut *self.vec; | |
1880 | // memmove back untouched tail, update to new length | |
1881 | let start = source_vec.len(); | |
1882 | let tail = self.tail_start; | |
1883 | let src = source_vec.as_ptr().offset(tail as isize); | |
1884 | let dst = source_vec.as_mut_ptr().offset(start as isize); | |
1885 | ptr::copy(src, dst, self.tail_len); | |
1886 | source_vec.set_len(start + self.tail_len); | |
1887 | } | |
1888 | } | |
1a4d82fc JJ |
1889 | } |
1890 | } | |
1891 | ||
d9579d0f AL |
1892 | |
1893 | #[stable(feature = "rust1", since = "1.0.0")] | |
1894 | impl<'a, T> ExactSizeIterator for Drain<'a, T> {} | |
1895 | ||
1a4d82fc JJ |
1896 | //////////////////////////////////////////////////////////////////////////////// |
1897 | // Conversion from &[T] to &Vec<T> | |
1898 | //////////////////////////////////////////////////////////////////////////////// | |
1899 | ||
1900 | /// Wrapper type providing a `&Vec<T>` reference via `Deref`. | |
85aaf69f SL |
1901 | #[unstable(feature = "collections")] |
1902 | pub struct DerefVec<'a, T:'a> { | |
1a4d82fc | 1903 | x: Vec<T>, |
85aaf69f | 1904 | l: PhantomData<&'a T>, |
1a4d82fc JJ |
1905 | } |
1906 | ||
85aaf69f | 1907 | #[unstable(feature = "collections")] |
1a4d82fc JJ |
1908 | impl<'a, T> Deref for DerefVec<'a, T> { |
1909 | type Target = Vec<T>; | |
1910 | ||
1911 | fn deref<'b>(&'b self) -> &'b Vec<T> { | |
1912 | &self.x | |
1913 | } | |
1914 | } | |
1915 | ||
1916 | // Prevent the inner `Vec<T>` from attempting to deallocate memory. | |
85aaf69f | 1917 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
1918 | impl<'a, T> Drop for DerefVec<'a, T> { |
1919 | fn drop(&mut self) { | |
1920 | self.x.len = 0; | |
1921 | self.x.cap = 0; | |
1922 | } | |
1923 | } | |
1924 | ||
9346a6ac | 1925 | /// Converts a slice to a wrapper type providing a `&Vec<T>` reference. |
bd371182 AL |
1926 | /// |
1927 | /// # Examples | |
1928 | /// | |
1929 | /// ``` | |
1930 | /// # #![feature(collections)] | |
1931 | /// use std::vec::as_vec; | |
1932 | /// | |
1933 | /// // Let's pretend we have a function that requires `&Vec<i32>` | |
1934 | /// fn vec_consumer(s: &Vec<i32>) { | |
1935 | /// assert_eq!(s, &[1, 2, 3]); | |
1936 | /// } | |
1937 | /// | |
1938 | /// // Provide a `&Vec<i32>` from a `&[i32]` without allocating | |
1939 | /// let values = [1, 2, 3]; | |
1940 | /// vec_consumer(&as_vec(&values)); | |
1941 | /// ``` | |
85aaf69f | 1942 | #[unstable(feature = "collections")] |
1a4d82fc JJ |
1943 | pub fn as_vec<'a, T>(x: &'a [T]) -> DerefVec<'a, T> { |
1944 | unsafe { | |
1945 | DerefVec { | |
1946 | x: Vec::from_raw_parts(x.as_ptr() as *mut T, x.len(), x.len()), | |
85aaf69f | 1947 | l: PhantomData, |
1a4d82fc JJ |
1948 | } |
1949 | } | |
1950 | } | |
1951 | ||
1952 | //////////////////////////////////////////////////////////////////////////////// | |
1953 | // Partial vec, used for map_in_place | |
1954 | //////////////////////////////////////////////////////////////////////////////// | |
1955 | ||
1956 | /// An owned, partially type-converted vector of elements with non-zero size. | |
1957 | /// | |
1958 | /// `T` and `U` must have the same, non-zero size. They must also have the same | |
1959 | /// alignment. | |
1960 | /// | |
1961 | /// When the destructor of this struct runs, all `U`s from `start_u` (incl.) to | |
1962 | /// `end_u` (excl.) and all `T`s from `start_t` (incl.) to `end_t` (excl.) are | |
1963 | /// destructed. Additionally the underlying storage of `vec` will be freed. | |
1964 | struct PartialVecNonZeroSized<T,U> { | |
1965 | vec: Vec<T>, | |
1966 | ||
1967 | start_u: *mut U, | |
1968 | end_u: *mut U, | |
1969 | start_t: *mut T, | |
1970 | end_t: *mut T, | |
85aaf69f SL |
1971 | |
1972 | _marker: PhantomData<U>, | |
1a4d82fc JJ |
1973 | } |
1974 | ||
1975 | /// An owned, partially type-converted vector of zero-sized elements. | |
1976 | /// | |
1977 | /// When the destructor of this struct runs, all `num_t` `T`s and `num_u` `U`s | |
1978 | /// are destructed. | |
1979 | struct PartialVecZeroSized<T,U> { | |
85aaf69f SL |
1980 | num_t: usize, |
1981 | num_u: usize, | |
1982 | marker: PhantomData<::core::cell::Cell<(T,U)>>, | |
1a4d82fc JJ |
1983 | } |
1984 | ||
1a4d82fc JJ |
1985 | impl<T,U> Drop for PartialVecNonZeroSized<T,U> { |
1986 | fn drop(&mut self) { | |
1987 | unsafe { | |
1988 | // `vec` hasn't been modified until now. As it has a length | |
1989 | // currently, this would run destructors of `T`s which might not be | |
1990 | // there. So at first, set `vec`s length to `0`. This must be done | |
1991 | // at first to remain memory-safe as the destructors of `U` or `T` | |
1992 | // might cause unwinding where `vec`s destructor would be executed. | |
1993 | self.vec.set_len(0); | |
1994 | ||
1995 | // We have instances of `U`s and `T`s in `vec`. Destruct them. | |
1996 | while self.start_u != self.end_u { | |
85aaf69f | 1997 | let _ = ptr::read(self.start_u); // Run a `U` destructor. |
1a4d82fc JJ |
1998 | self.start_u = self.start_u.offset(1); |
1999 | } | |
2000 | while self.start_t != self.end_t { | |
85aaf69f | 2001 | let _ = ptr::read(self.start_t); // Run a `T` destructor. |
1a4d82fc JJ |
2002 | self.start_t = self.start_t.offset(1); |
2003 | } | |
2004 | // After this destructor ran, the destructor of `vec` will run, | |
2005 | // deallocating the underlying memory. | |
2006 | } | |
2007 | } | |
2008 | } | |
2009 | ||
1a4d82fc JJ |
2010 | impl<T,U> Drop for PartialVecZeroSized<T,U> { |
2011 | fn drop(&mut self) { | |
2012 | unsafe { | |
2013 | // Destruct the instances of `T` and `U` this struct owns. | |
2014 | while self.num_t != 0 { | |
2015 | let _: T = mem::uninitialized(); // Run a `T` destructor. | |
2016 | self.num_t -= 1; | |
2017 | } | |
2018 | while self.num_u != 0 { | |
2019 | let _: U = mem::uninitialized(); // Run a `U` destructor. | |
2020 | self.num_u -= 1; | |
2021 | } | |
2022 | } | |
2023 | } | |
2024 | } |